The 640 MEG Shareware Studio 2/The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO/windows/fc_11f.zip/FILECMDR.MA$

Text File | 1992-06-14 | 316KB | 11,460 lines

                                      TUTORIAL


     Well, we admit it, we're still working on the documentation.
     There are over 200 pages of it in this file.  We're working on
     it every day.

     The information in this file is generally correct.  The function
     reference section is complete.  The WIL language tutorial is
     quite strong.  The information on how to build menus is correct
     as far as it goes, but is a tad dated.  Some of it refers to
     another one of our products with a similiar menu structure
     (Command Post).  Where any serious problems occur, or where new
     functions make a previously hard task simple, we've dropped in
     a special comment in the form:

           #### Hi This is a special comment ####

     to keep you from going too far astray.






                                     MENU FILES




       What is a Menu File?
       Menus are defined in standard ASCII text files (the kind created by
       Notepad).  See your product documentation for the name of the default
       menu file that it uses.

       Every menu file contains menu items which appear in the dropdown
       menus, and may also contain top-level menu names which show up in a
       main menu bar (refer to your product documentation for more
       information).  For each menu item, you'll have one or more lines of
       commands which the WIL Interpreter will execute when you choose that
       item. Your menu will "feel" just like a regular Windows menu, but it
       will manage things in a way tailored to suit your needs.




       How to Create a Simple Menu
       Using Windows Notepad, open the menu file, and scroll down to the end.
       We're going to add a new menu specifically for desktop publishing
       applications.

       First off, let's name our new menu. Starting in the first column (at
       the far left), type:

        &DTP Apps


       Because it begins in column 1, this entry defines a top-level menu
       item.  Depending on the product you are using, it may either appear on
       a menu bar or it may appear on the first-level dropdown menu.  The "&"
       is optional ---
                        it defines an Alt-key combination for the entry; Alt-
       D in this example.  It will appear in the menu as "DTP Apps"..

       Since we intend to use PageMaker for our projects, we'll define a menu
       item which lets us launch it. On the next line, beginning in column 2
       (indented one space), type:

         &PageMaker 4.0


       Below this menu item, we will enter the commands which let you launch
       PageMaker.  These begin in column 5 or more (or you can tab once).
       There are almost a hundred functions and commands in the Windows
       Interface Language (WIL), but it takes only a few to get started.

       Well, what did we do to start PageMaker before we had Command Post?
       We had to make sure we're in the proper drive, find the PageMaker
       executable file, and doubleclick or run it.  We can put those steps in
       our PageMaker menu with the DirChange and Run functions:





        &DTP Apps
         &PageMaker 4.0
           DirChange("C:\pm\docs")
           Run("pm.exe","")


       DirChange("C:\pm\docs") tells Command Post to change to the D: drive
       and find the \PM\DOCS subdirectory. Run("pm.exe", "") tells Command
       Post to launch the PM.EXE application, with no parameters passed to
       it.

       Our simple menu is complete.  Now save the file and exit Notepad.
       Then choose Reload Menu from Command Post's system menu box so our new
       menu will take effect.




       Enhancing Our Menu
       Let's imagine that we have a special publishing project ("The Waldorf
       Salad Cookbook" - should sell millions) that we've been working on
       over a series of months. It has its own subdirectory, C:\PM\WALDORF,
       and several PageMaker files - CHPTR1.PM4, CHPTR2.PM4, etc.  We would
       like to have a separate menu item for each chapter so we can start
       PageMaker with the chapter already loaded. We always use PageMaker at
       full-screen, so we'd rather not have to press the Maximize box
       whenever the program starts.  Also, we would like to launch the
       CLIPBRD.EXE utility as an icon, since we check the clipboard often.
       Let's create the first menu item , which will follow the generic
       PageMaker 4.0 item we created above.

       Since this is a submenu item, it starts in column 2:

         PM-&Waldorf
           DirChange ("C:\pm\waldorf")
           RunZoom ("pm.exe", "chptr1.pm4")
           RunIcon ("clipbrd.exe","")


       Our menu item now does a lot of  work for us.  The RunZoom command has
       a new parameter, "chptr1.pm4", which tells PageMaker which file to
       load when it starts up.  The command RunIcon launches the Clipboard
       viewer as an icon.

       We could define more menu items for the other chapters, and find
       ourselves getting to work faster and easier than before.  Not to
       mention helping other people work on the project without getting lost
       in our particular directory structure.




       An Enhancement for Safety
       After spending 45 hours on CHPTR1.PM4, we start to worry a bit about
       losing our work.  We decide to make a diskette backup of our chapter
       at the beginning of each session.  We'll make it a part of the menu!
       It now looks like this:





         PM-Waldorf Ch &1
           DirChange ("C:\pm\waldorf")
           ;Backup the current file first...
           Pause ("Backup Chapter 1","Put Backup disk in Drive A:")
           FileCopy ("Chptr1.pm4","a:chptr1.pm4",@FALSE)
           RunZoom ("pm.exe", "chptr1.pm4")
           RunIcon ("clipbrd.exe","")


       Our menu changes to the proper directory, and now displays a dialog
       box with the title "Backup Chapter 1", prompting the user to "Put
       Backup disk in Drive A:".  The Pause function also creates OK and
       Cancel buttons which let the user get out of the menu item (where did
       I put that disk???) or continue.  If OK is clicked, FileCopy copies
       the source file CHPTR1.PM4 to the destination A:CHPTR1.PM4.  The
       @FALSE is a WIL constant which specifies that we do not want to prompt
       the user if the file already exists in the target directory.

       It's a good idea to put comments in the file when you're trying to
       accomplish something complex.  Comments start with a semicolon; the
       rest of the line is ignored.

       This menu item is getting a bit complicated, but look at what we've
       accomplished. You've automated the backup process, and made it hard to
       forget. You don't have to memorize all those manual steps, and you
       don't have to teach them to others. Menus make your life easier, and
       in this case let you sleep easier too!








       Other Useful Functions

       CurrentFile ( )
       Returns the name of the selected file (the one with the dotted
       rectangle around it) from the Command Post window.  (See pg. 64)

       Example:
        &Editing
         Run &Notepad with selected file
          Run ("Notepad", CurrentFile())


       DirChange (pathname)
       Changes the directory to the pathname specified.  (See pg. 75)

       Example:
        &Miscellany
         &Run some program not in path
          DirChange ("c:\some\dir\not\in\path")
          Run ("Obscure.exe","")



       Fun With Filenames
       Sometimes you need to take a pathname and extract the drive letter,
       directory path, or filename from it.  The WIL string functions help
       you do this.

       Getting the drive letter is relatively easy.  Just make sure there's a
       colon in the pathname in at least the second character position.  If
       there is, take the character just before it:

          FullPath = AskLine ("", "Enter a full pathname", "")
          ColonIsAt= StrIndex(FullPath, ":",1, @FWDSCAN)
          ;if no colon or is first char, return "" drive letter:
          LetterLen = Min (Max (ColonIsAt-1, 1), 0)
          DriveLetter = StrSub(FullPath, ColonIsAt-1, 1)
          Drop (ColonIsAt, LetterLen)

       The colon could come later than position #2 if the pathname includes a
       network address before the drive letter.

       Getting the directory path is accomplished by finding the last
       backslash character and taking everything before that point.  Note
       when using StrIndex to search backwards from the end of a string, we
       use a start position of 0:
       #### Use FilePath() function instead here ####
          Slash= StrIndex (FullPath, "\", 0,   @BACKSCAN)
          DirPath = StrSub (FullPath, 1, Slash-1)
          Drop (Slash)

       The filename is extracted in a similar manner:



       #### Use the FileRoot and FileExtension functions here instead ####

          Slash = StrIndex (FullPath, "\",          0,   @BACKSCAN)
          FName = StrSub (FullPath, Slash+1,
                                                    StrLen(FullPath)    -
        Slash)
          Drop (Slash)

       Once you have a filename you can extract its root.  First find the
       dot.  If there isn't any, proceed as if it was at the end.  In either
       case take the portion of the filename before the dot:

          DotIsAt = StrIndex (FileName,".",0,@FWDSCAN)
          DotIsAt = DotIsAt*(DotIsAt!=0)
                                     + (StrLen(FileName)+1)*(DotIsAt==0)
          RootFileName=StrSub (FileName,1,DotIsAt-1)
          Drop (DotIsAt)

       Getting the extension is easier:

          DotIsAt = StrIndex (FileName,".",0,@FWDSCAN)
          Terminate (DotIsAt==0,"","File has no extension")
          Ext= StrSub (FileName, DotIsAt+1, StrLen(FileName)-DotIsAt)
          Drop (DotIsAt)



       Making a Free-Floating Menu
       The Command Post directory window, coupled with the default menu in
       CMDPOST.CPM, provides you with a more-useful file manager than is
       provided by Windows version 2.x.  However there are times when all
       you'd rather see is your custom menu bar without the directory
       listing, perhaps nestled down at the lower-right hand corner of the
       screen.

       This can be done rather easily in the initialization section of your
       custom menu file with the WinPlace command:

          ThisWin = WinGetActive()
          WinTitle (ThisWin, "Jenny's Favorites")
          ;get these dimensions from WININFO.EXE:
          WinPlace (710,872,1000,966,"Jenny's Favorites")



       When a Program is Already Running
       When you launch a program from a menu and it's already running, some
       times you'd rather just activate the window that's running instead of
       invoking another instance of the same program:

        &Desktop
         &Clock
          ErrorMode (@OFF)           ; Turn Errors Off
          Terminate (WinActivate("Clock"),"","")    ; Already running
          ErrorMode (@CANCEL)             ; Re-enable default error mode
          Run ("Clock.exe","")








       Working With Lists
       When selecting a menu item to run an application program, you can
       choose a file for the program to open from among all the appropriate
       files in the current directory.  For example, assume we want to choose
       from among the .WRI files, and then run Windows Write with the one we
       highlighted.  If the user presses OK without selecting a file, we'll
       still run Write, but we won't open a file:

          HTab = Num2Char (09)
          WRIFiles = FileItemize("*.WRI")
          TheFile = ItemSelect(".WRI file,
                                or just OK for new file",WRIFiles, HTab)
          RunZoom ("Write.exe", TheFile)
          Drop (WRIFiles, TheFile, HTab)

       We don't have to restrict ourselves to a single wildcard when we
       itemize files.  And if we've set up an association between the file
       extensions we're itemizing on and the programs that create them, we
       don't have to restrict ourselves to a single program, either.

       For example, let's show a list of all our compressed files in the
       current directory, allow the user to choose one, and run the
       appropriate decompression program against it.  (This assumes we've set
       up associations between these extensions and their respective
       compression programs in WIN.INI's [Extensions] section):

        &Utilities
         &Compress a file
          Files = FileItemize ("*.ZIP *.LZH *.ARC *.PAK *.PKA")
          TheFile = ItemSelect ("Choose a File", FileList, " ")
          Run (TheFile,"")
          Drop(FileList, TheFile)

       Of course, we don't have to itemize just by extension, either.  Any
       kind of wildcard will do.  We can even itemize full pathnames.






                                     BATCH FILES




       WIL Basics



       What is a Batch File?
       A batch file, whether a DOS batch file or a WIL file, is simply a list
       of commands for the computer to process.  Any task which will be run
       more than once, or which requires entering many commands or even a
       single complex command, is a candidate for a batch file.  For example,
       suppose you regularly enter the following commands to start Windows:

       First:

        cd\windows

       then:

        win

       and then:

        cd\

       Here, you are changing to the Windows directory, running Windows, and
       then returning to the root directory.  Instead of having to type these
       three commands every time you run Windows, you can create a DOS batch
       file, called WI.BAT, which contains those exact same commands:

        cd\windows
        win
        cd\

       Now, to start Windows, you merely need to type the single command WI,
       which runs the WI.BAT batch file, which executes your three commands.

       WIL files work basically the same way.




       Our First WIL File
       Our first WIL file will simply run our favorite Windows application:
       Solitaire.  First, start up Notepad, or any other editor which is
       capable of saving text in pure ASCII format (may we suggest WinEdit,
       from Wilson WindowWare).  Enter the following line of text:

        Run("sol.exe", "")

       Save the file with the name SOLITARE.WBT.  Now, run SOLITARE.WBT by
       starting or switching to the File Manager (or MS-DOS Executive), and
       either moving the cursor to the file name and pressing Enter, or





       double-clicking on the file name with your mouse.  Presto!  It's
       Solitaire.

       Okay, that wasn't really so impressive.  But it did serve to
       illustrate several important WIL points.  They are:

       1.   WIL files must be edited and saved in ASCII format.

       2.   WIL files should be given a WBT extension.  When WIL is first
         installed, it creates an entry in your WIN.INI file which causes
         files with a WBT extension to be associated with WIL.  As long as
         WIL.EXE is located in your DOS path, you can place WBT files in any
         directory and run them by simply selecting them, as we did above.

       3.   After you have created a WBT file, you run it by moving your
         cursor to it and pressing Enter, or double-clicking on it with your
         mouse (you can also add a WBT file to a program group and run it
         using the Program Manager; see your Windows manual for further
         information).  Whatever method you use, we'll use the term Run to
         refer to selecting and running the file.




       Functions and Parameters
       Now, let's look more closely at the line we entered:

        Run("sol.exe", "")

       The first part, Run, is a WIL function.  As you might have guessed,
       its purpose is to run a Windows program.  There are over a hundred
       different functions and commands in WIL, and each has a certain syntax
       which must be used.  The correct syntax for all WIL functions may be
       found in the WIL Function Reference (pg. 55).  The entry for Run
       starts off as follows:


       Syntax:
        Run (program-name, parameters)

       Parameters:
        "program-name" =the name of the desired .EXE, .COM, .PIF, .BAT file,
                     or a data file.
        "parameters" =     optional parameters as required by the
                     application.


       Like all WIL functions, Run is followed by a number of parameters,
       enclosed in parentheses.  Parameters are simply additional information
       which are provided when a particular function is used; they may be
       either required or optional.  Optional parameters are indicated by
       being enclosed in square brackets.  In this case, Run has two required
       parameters: the name of the program to run, and the parameters to be
       passed to the program.

       WIL functions use several types of parameters.  Multiple parameters
       are separated by commas.  In the example





        Run("sol.exe", "")

       "sol.exe" and "" are both string constants.  String constants can be
       identified by the quote marks which delimit (surround) them.  You may
       use either double ("), single forward (') or single back (`) quote
       marks as string delimiters; the examples in this manual will use
       double quotes.

       You may have noticed how we said earlier that the two parameters for
       the Run function are required, and yet the entry for Run in the WIL
       Function Reference describes the second parameter -- "parameters" --
       as being optional.  Which is correct?  Well, from a language
       standpoint, the second parameter is required.  That is, if you omit
       it, you will get a syntax error, and your batch file will not run
       properly.  However, the program that you are running may not need any
       parameters.  Solitaire, for example, does not take any parameters.
       The way we handle this in our batch file is to specify a null string -
       - two quote marks with nothing in between -- as the second parameter,
       as we have done in our example above.

       To illustrate this further, let's create a WIL file called EDIT.WBT,
       containing the following line:

        Run("notepad.exe", "")

       This is just like our previous file, with only the name of the program
       having been changed.  Save the file, and run it.  You should now be in
       Notepad.  Now edit the EDIT.WBT file as follows:

        Run("notepad.exe", "solitare.wbt")

       Save the file, exit Notepad, and run EDIT.WBT again.  You should now
       be in Notepad, with SOLITARE.WBT loaded.  As we've just demonstrated,
       Notepad is an example of a program which can be run with or without a
       file name parameter passed to it by WIL.

       Before you leave Notepad, modify EDIT.WBT as follows:

        ; This is an example of the Run function in WIL
        Run("notepad.exe", "solitare.wbt")

       The semicolon at the beginning of the first line signifies a comment,
       and causes that line to be ignored.  You can place comment lines,
       and/or blank lines anywhere in your WIL files.  In addition, you can
       place a comment on the same line as a function by preceding the
       comment with a semicolon.  For example:

        Run("sol.exe", "")   ; this is a very useful function

       Everything to the right of a semicolon is ignored.  However, if a
       semicolon appears in a string delimited by quotes, it is treated as
       part of the string.








       Displaying Text
       Now, let's modify our SOLITARE.WBT file as follows.  You might as well
       use the EDIT.WBT batch file you created earlier to start up Notepad:

        ; solitare.wbt
        Display(5, "Good Luck!", "Remember ... it's only a game.")
        Run("sol.exe", "")

       And run it.  Notice the message box which pops up on the screen with
       words of encouragement:









       That's done by the Display function in the second line above.  Here's
       the reference for Display:


       Syntax:
        Display (seconds, title, text)

       Parameters:
        seconds =    integer seconds to display the message (1-15).
        "title" =    Title of the window to be displayed.
        "text" =     Text of the window to be displayed.


       Note that the Display function has three parameters.  The first
       parameter -- in our example, 5 -- is the number of seconds which the
       display box will remain on the screen (you can make the box disappear
       before then by pressing any key or mouse button).  This is a numeric
       constant, and -- unlike string constants -- it does not need to be
       enclosed in quotes (although it can be, if you wish, as WIL will
       automatically try to convert string variables to numeric variables
       when necessary, and vice versa).  The second parameter is the title of
       the message box, and the third parameter is the actual text displayed
       in the box.  Now, exit Solitaire (if you haven't already done so), and
       edit SOLITARE.WBT by placing a semicolon at the beginning of the line
       with the Run function.  This is a handy way to disable, or "comment
       out," lines in your WIL files when you want to modify and test only
       certain segments.  Your SOLITARE.WBT file should look like this:

        ; solitare.wbt
        Display(5, "Good Luck!", "Remember ... it's only a game.")
        ; Run("sol.exe", "")

       Now, experiment with modifying the parameters in the Display function.
       Try adjusting the value of the first parameter.  If you look up
       Display in the WIL reference section, you will see that the acceptable





       values for this parameter are 1-15.  If you use a value outside this
       range, WIL will adjust it to "make it fit"; that is, it will treat
       numbers less than 1 as if they were 1, and numbers greater than 15 as
       15.  Experiment.  Also, try using a non-integer value, such as 2.5,
       and see what happens.  Play around with the text in the two string
       parameters; try making one, or both, null strings ("").




       Getting Input
       Now, let's look at ways of getting input from a user and making
       decisions based on that input.  The most basic form of input is a
       simple Yes/No response, and, indeed, there is a WIL function called
       AskYesNo:


       Syntax:
        AskYesNo (title, question)

       Parameters
        "title" =    title of the question box.
        "question" = question to be put to the user.

       Returns:
        (integer)    @YES or @NO, depending on the button pressed.


       You should be familiar with the standard syntax format by now; it
       shows us that AskYesNo has two required parameters.  The Parameters
       section tells us that these parameters both take strings (indicated by
       the quote marks), and tells us what each of the parameters means.

       You will notice that there is also a new section here, titled Returns.
       This section shows you the possible values that may be returned by
       this function.  All functions return values.  We weren't concerned
       with the values returned by the Run and Display functions.  But with
       AskYesNo, the returned value is very important, because we will need
       that information to decide how to proceed.  We see that AskYesNo
       returns an integer value.  An integer is a whole (non-fractional)
       number, such as 0, 1, or 2 (the number 1.5 is not an integer).  We
       also see that the integer value returned by AskYesNo is either @YES or
       @NO.  @YES and @NO are predefined constants in WIL.  All predefined
       constants begin with an @ symbol, and we will distinguish them further
       by typing them in all caps.  You will find a list of all predefined
       constants in Appendix A (pg. 185).  Even though the words Yes and No
       are strings, it is important to remember that the predefined constants
       @YES and @NO are not string variables (actually, @YES is equal to 1,
       and @NO is equal to 0.  Don't worry if this is confusing; you don't
       need to remember it).

       Now, let's modify our SOLITARE.WBT file as follows:

        AskYesNo("Really?", "Play Solitaire now?")
        Run("sol.exe", "")





       and run it.  You should have gotten a nice dialog box which asked if
       you wanted to play Solitaire:













       but no matter what you answered, it started Solitaire anyway.  This is
       not very useful.  We need a way to use the Yes/No response to
       determine further processing.  First, we need to explore the concept
       and use of variables.




       Using Variables
       A variable is simply a placeholder for a value.  The value that the
       variable stands for can be either a text string (string variable) or a
       number (numeric variable).  You may remember from Algebra 101 that if
       X=3, then X+X=6.  X is simply a numeric variable, which stands here
       for the number 3.  If we change the value of X to 4 (X=4), then the
       expression X+X is now equal to 8.

       Okay.  We know that the AskYesNo function returns a value of either
       @YES or @NO.  What we need to do is create a variable to store the
       value that AskYesNo returns, so that we can use it later on in our
       batch file.  First, we need to give this variable a name.  In WIL,
       variable names must begin with a letter, may contain any combination
       of letters or numbers, and may be from 1 to 30 characters long.  So,
       let's use a variable called response (we will distinguish variable
       names in this text by typing them in all lowercase letters; we will
       type function and command names starting with a capital letter.
       However, in WIL, the case is not significant, so you can use all
       lowercase, or all uppercase, or whatever combination you prefer).  We
       assign the value returned by AskYesNo to the variable response, as
       follows:

        response = AskYesNo("Really?", "Play Solitaire now?")

       Notice the syntax.  The way that WIL processes this line is to first
       evaluate the result of the AskYesNo function.  The function returns a
       value of either @YES or @NO.  Then, WIL assigns this returned value to
       response.  Therefore, response is now equal to either @YES or @NO,
       depending on what the user enters.

       Now, we need a way to make a decision based upon this variable.








       Making Decisions
       WIL provides a way to conditionally execute a statement, and that is
       by using the If ... Then command.  Actually, there are two separate
       parts to this construct: If and Then.  The format is:

          If condition Then statement

       (We refer to If ... Then as a command, rather than a function, because
       functions are followed by parameters in parentheses, while commands
       are not.  Commands are used for system control.)

       The use of If ... Then can easily be illustrated by going back to our
       SOLITARE.WBT file, and making these modifications:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @YES Then Run("sol.exe", "")

       In this example, we are using If ... Then to test whether the value of
       the variable response is @YES.  If it is @YES, we start Solitaire.  If
       it isn't @YES, we don't.  The rule is: if the condition following the
       If keyword is true, then the statement following the Then keyword is
       performed.  If the condition following the If keyword is false, then
       anything following the Then keyword is ignored.

       There is something extremely important that you should note about the
       syntax of the If ... Then command: the double equal signs (==).  In
       WIL, a single equal sign (=) is an assignment operator -- it assigns
       the value on the right of the equal sign to the variable on the left
       of the equal sign.  As in:

        response = AskYesNo("Really?", "Play Solitaire now?")

       This is saying, in English: "Assign the value returned by the AskYesNo
       function to the variable named response."  But in the statement:

        If response == @YES Then Run("sol.exe", "")

       we do not want to assign a new value to response, we merely want to
       test whether it is equal to @YES.  Therefore, we use the double equal
       signs (==), which is the equality operator in WIL.  The statement
       above is saying, in English: "If the value of the variable named
       response is equal to @YES, then run the program SOL.EXE."  If you used
       a single equal sign (=) here by mistake, you would get an error
       message:







       Which is WIL's way of telling you to re-check your syntax.

       If you've become confused, just remember that a single equal sign (=)
       is an assignment operator, used to assign a value to a variable.
       Double equal signs (==) are an equality operator, used to test whether
       the values on both sides of the operator are the same.  If you have a
       problem with one of your WIL files, make sure to check whether you've
       used one of these symbols incorrectly.  It's a very common mistake,
       which is why we emphasize it so strongly!

       We've seen what happens when the condition following the Then keyword
       is true.  But what happens when it is false?  Remember we said that
       when the If condition is false, the Then statement is ignored.  There
       will be times, however when we want to perform an alternate action in
       this circumstance.  For example, suppose we want to display a message
       if the user decides that he or she doesn't want to play Solitaire.  We
       could write:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @YES Then Run("sol.exe", "")
        If response == @NO Then Display(5, "", "Game canceled")

       In this case there are two If statements being evaluated, with one and
       only one of them possibly being true (unless the user selects Cancel,
       which would abort the batch file entirely).  However, this is
       inefficient from a processing standpoint.  Furthermore, what would
       happen if you had several functions you wanted to perform if the user
       answered Yes?  You would end up with something unwieldy:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @YES Then Display(5, "", "On your mark ...")
        If response == @YES Then Display(5, "", "Get set ...")
        If response == @YES Then Display(5, "", "Go!")
        If response == @YES Then Run("sol.exe", "")

       Clearly, there must be a better way of handling this.




       Branching
       Enter the Goto command.  Goto, in combination with If ... Then, gives
       you the ability to redirect the flow of control in your WIL files.
       Goto does exactly what it says -- it causes the flow of control to go
       to another point in the batch file.  You must specify where you want
       the flow of control to be transferred, and you must mark this point
       with a label.  A label is simply a destination address, or marker.
       The form of the Goto command is:

          Goto label

       where label is an identifier that you specify.  The same rules apply
       to label names as to variable names (the first character must be a
       letter, the label name may consist of any combination of letters and
       numbers, and the label name may be from 1 to 30 characters long).  In





       addition, the label is preceded by a colon (:) at the point where it
       is being used as a destination address.  Here's an example:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @NO Then Goto quit
        Display(5, "", "On your mark ...")
        Display(5, "", "Get set ...")
        Display(5, "", "Go!")
        Run("sol.exe", "")
        :quit

       If the If condition is true (that is, if the user answers No), then
       the Goto statement is performed.  The Goto statement is saying, in
       English "go to the line marked :quit, and continue processing from
       there."  Notice how the label quit is preceded by a colon on the last
       line, but not on the line where it follows the Goto keyword.  This is
       important.  Although you can have multiple lines in your batch file
       which say Goto quit, you can have only one line marked :quit (just
       like you can have several people going to your house, but can have
       only one house with a particular address).  Of course, you can use
       many different labels in a batch file, just as you can use many
       different variables, as long as each has a unique name.  For example:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @NO Then Goto quit
        Display(5, "", "On your mark ...")
        Display(5, "", "Get set ...")
        Display(5, "", "Go!")
        Run("sol.exe", "")
        Goto done
        :quit
        Display(5, "", "Game canceled")
        :done

       This is a little more complicated.  It uses two labels, quit and done.
       If the user answers No, then the If condition is true, control passes
       to the line marked :quit, and a message is displayed.  If, on the
       other hand, the user answers Yes, then the If condition is false, and
       the Goto quit line is ignored.  Instead, the next four lines are
       processed, and then the Goto done statement is performed.  The purpose
       of this line is to bypass the Display line which follows, by
       transferring control to the end of the batch file.  There is another
       way to keep your batch file processing from "falling through" to
       unwanted lines at the end of a program, and that is with the Exit
       command.  Exit causes a batch file to end immediately.  So, for
       example, we could rewrite the above batch file as follows:

        response = AskYesNo("Really?", "Play Solitaire now?")
        If response == @NO Then Goto quit
        Display(5, "", "On your mark ...")
        Display(5, "", "Get set ...")
        Display(5, "", "Go!")
        Run("sol.exe", "")
        Exit
        :quit
        Display(5, "", "Game canceled")





       Since the Run function is the last thing we want to do if the user
       answers Yes, the Exit command simply ends the program at that point.
       Note that we could put an Exit command at the end of the program as
       well, but it isn't necessary.  An Exit is implied at the end of a WIL
       program.



       This concludes the first part of our tutorial.  You now have the
       building blocks you need to create useful WIL files.  In the second
       part, which follows, we will look in more detail at some of the WIL
       functions which are available for your use.




       Exploring WIL
       What follows is just a sample of the many functions and commands
       available in WIL.  These should be sufficient to begin creating
       versatile and powerful batch files.  For complete information on these
       and all WIL functions and commands, refer to the WIL Function
       Reference (pg. 55).




       Running Programs
       There are three functions which you can use to start an application,
       each of which shares a common syntax:


       Run (program-name, parameters)
       We've already seen the Run function.  This function starts a program
       in a "normal" window.  Windows decides where to place the
       application's  window on the screen.

       Example:
        Run("notepad.exe", "myfile.txt")

       If the program has an EXE extension, its extension may be omitted:

        Run("notepad", "myfile.txt")

       Also, you can "run" data files if they have an extension in WIN.INI
       which is associated with an executable program.  So, if TXT files are
       associated with Notepad:

        Run("myfile.txt", "")

       would start Notepad, using the file MYFILE.TXT.

       When you specify a file to run, WIL looks first in the current
       directory, and then in the directories on your DOS path.  If the file
       is not found, WIL will return an error.  You can also specify a full
       path name for WIL to use, as in:

        Run("c:\windows\apps\winedit.exe", "")






       RunZoom (program-name, parameters)
       RunZoom is like Run, but starts a program as a full-screen window.

       Example:
        RunZoom("excel", "bigsheet.xls")

       RunIcon (program-name, parameters)
       RunIcon starts a program as an icon at the bottom of the screen.

       Example:
        RunIcon("clock", "")



       Display and Input
       Here we have functions which display information to the user and
       prompt the user for information, plus a couple of relevant system
       functions.


       Display (seconds, title, text)
       Displays a message to the user for a specified period of time.  The
       message will disappear after the time expires, or after any keypress
       or mouse click.

       Example:
        Display(2, "", "Loading Solitaire now")








       Message (title, text)
       This command displays a message box with a title and text you specify,
       which will remain on the screen until the user presses the OK button.

       Example:
        Message("Sorry", "That file cannot be found")










       Pause (title, text)
       This command is similar to Message, except an exclamation-point icon
       appears in the message box, and the user can press OK or Cancel.  If
       the user presses Cancel, the batch file exits.





       Example:
        Pause("Delete Backups", "Last chance to stop!")
        ; if batch file gets this far, the user pressed OK
        FileDelete("*.bak")










       AskYesNo (title, question)
       Displays a dialog box with a given title, which presents the user with
       three buttons: Yes, No, and Cancel.  If the user selects the Cancel
       button, the batch file is terminated.

       Example:
        response = AskYesNo("End Session", "Really quit Windows?")










       AskLine (title, prompt, default)
       Displays a dialog box with a given title, which prompts the user for a
       line of input.  Returns the default if the user just presses the OK
       button.

       Example:
        yourfile = AskLine("Edit File", "Filename:", "newfile.txt")
        Run("notepad", yourfile)














       If you specify a default value (as we have with NEWFILE.TXT), it will
       appear in the response box, and will be replaced with whatever the
       user types.  If the user doesn't type anything, the default is used.






       Beep
       Beeps once.

        Beep

       And if one beep isn't enough for you:

        Beep
        Beep
        Beep

       Delay (seconds)
       Pauses batch file execution.

       The Delay function lets you suspend batch file processing for 1 to 15
       seconds.  You can use multiple occurrences for a longer delay:

        Delay(15)
        Delay(15)

       Will insert a 30-second pause.




       Manipulating Windows
       There are a large number of functions which allow you to manage the
       windows on your desktop.  Here are some of them:


       WinZoom (partial-windowname)
       Maximizes an application window to full-screen.


       WinIconize (partial-windowname)
       Turns an application window into an icon.


       WinShow (partial-windowname)
       Shows a window in its "normal" state.



       These three functions are used to modify the size of an already-
       running window.  WinZoom is the equivalent of selecting Maximize from
       a window's control menu, WinIconize is like selecting Minimize, and
       WinShow is like selecting Restore.

       The window on which you are performing any of these functions does not
       have to be the active window.  If the specified window is in the
       background, and a WinZoom or WinShow function causes the size of the
       window to change, then the window will be brought to the foreground.
       The WinZoom function has no effect on a window which is already
       maximized; likewise, WinShow has no effect on a window which is
       already "normal."





       Each of these functions accepts a partial windowname as a parameter.
       The windowname is the name which appears in the title bar at the top
       of the window.  You can specify the full name if you wish, but it may
       often be advantageous not to have to do so.  For example, if you are
       editing the file SOLITARE.WBT in a Notepad window, the windowname will
       be Notepad - SOLITARE.WBT:






















       You probably don't want to have to hard-code this entire name into
       your batch file as:

        WinZoom("Notepad - SOLITARE.WBT")

       Instead, you can specify the partial windowname "Notepad":

        WinZoom("Notepad")

       If you have more than one Notepad window open, WIL will use the one
       which was most recently used or started.

       Note that WIL matches the partial windowname beginning with the first
       character, so that while

        WinZoom("Note")

       would be correct,

        WinZoom("pad")

       would not result in a match.

       Also, the case (upper or lower) of the title is significant, so

        WinZoom("notepad")

       would not work either.






       WinActivate (partial-windowname)
       Makes an application window the active window.

       This function makes a currently-open window the active window.  If the
       specified window is an icon, it will be restored to normal size;
       otherwise, its size will not be changed.


       WinClose (partial-windowname)
       Closes an application window.

       This is like selecting Close from an application's control menu.  You
       will still receive any closing message(s) that the application would
       normally give you, such as an "unsaved-file" dialog box.


       WinCloseNot (partial-windowname
            [, partial-windowname]...)
       Closes all application windows except those specified.

       This function lets you close all windows except the one(s) you want to
       remain open.  For example:

        WinCloseNot("Program Man")

       would leave only the Program Manager open, and:

        WinCloseNot("Program Man", "Solit")

       would leave the Program Manager and Solitaire windows open.


       WinWaitClose (partial-windowname)
       Waits until an application window is closed.

       This function causes your WIL file to pause until you have manually
       closed a specified window.  This is a convenient way to get WIL to
       open several windows sequentially, thereby not having unnecessary
       windows all over your desktop.  For example:

        RunZoom("invoices.xls", "")       ;balance the books
        WinWaitClose("Microsoft Ex")      ;wait till Excel closed
        RunZoom("sol", "")                     ;you deserve a break
        WinWaitClose("Solitaire")              ;wait until Solit closed
        Run("winword", "agenda.doc")      ;more paperwork
        WinWaitClose("Microsoft Wor")          ;wait until W4W closed
        Run("clock","")                        ;lunchtime yet?

       During the time that the batch file is suspended, the WIL icon will
       remain at the bottom of your screen.  You can cancel the batch file at
       any time by selecting Terminate from the icon's control menu.


       WinExist (partial-windowname)
       Tells if a window exists.





       This function returns @TRUE or @FALSE, depending on whether a matching
       window can be found.  This provides a way of insuring that only one
       copy of a given window will be open at a time.

       If you've been following this tutorial faithfully from the beginning,
       you probably have several copies of Solitaire running at the moment.
       (You can check by pressing Ctrl-Esc and bringing up the Task Manager.
       You say you've got five Solitaire windows open?  Okay, close them
       all.)  Now, let's modify our SOLITARE.WBT file.  First, trim out the
       excess lines so that it looks like this:

        Run("sol.exe", "")

       Now, let's use the WinExist function to make sure that WIL only starts
       Solitaire if it isn't already running:

        If WinExist("Solitaire") == @FALSE Then Run("sol.exe", "")

       And this should work fine.  Run SOLITARE.WBT twice now, and see what
       happens.  The first time you run it, it should start Solitaire; the
       second (and subsequent) time, it should not do anything.

       However, it's quite likely that you want the batch file to do
       something if Solitaire is already running -- namely, bring the
       Solitaire window to the foreground.  This can be accomplished by using
       the WinActivate function, along with a couple of Goto statements:

        If WinExist("Solitaire") == @FALSE Then Goto open
        WinActivate("Solitaire")
        Goto loaded
        :open
        Run("sol.exe", "")
        :loaded

       Note that we can change this to have WinExist check for a True value
       instead, by modifying the structure of the batch file:

        If WinExist("Solitaire") == @TRUE Then Goto activate
        Run("sol.exe", "")
        Goto loaded
        :activate
        WinActivate("Solitaire")
        :loaded

       Either format is perfectly correct, and the choice of which to use is
       merely a matter of personal style.  The result is exactly the same.


       EndSession ( )
       Ends the current Windows session.

       This does exactly what it says.  It will not ask any questions
       (although you will receive any closing messages that your currently-
       open windows would normally display), so you may want to build in a
       little safety net:





        sure = AskYesNo("End Session", "Really quit Windows?")
        If sure == @YES Then EndSession()

       EndSession is an example of a WIL function which does not take any
       parameters, as indicated by the empty parentheses which follow it.
       The parentheses are still required, though.




       Files and Directories

       DirChange (pathname)
       Changes the directory to the pathname specified.

       Use this function when you want to run a program which must be started
       from its own directory.  "Pathname" may optionally include a drive
       letter.

       Example:
        DirChange("c:\windows\winword")
        Run("winword.exe", "")

       DirGet ( )
       Gets the current working directory.

       This function is especially useful when used in conjunction with
       DirChange, to save and then return to the current directory.

       Example:
        origdir = DirGet()
        DirChange("c:\windows\winword")
        Run("winword.exe", "")
        DirChange(origdir)

       FileExist (filename)
       Determines if a file exists.

       This function will return @TRUE if the specified file exists, and
       @FALSE if it doesn't exist.

       Example:
        If FileExist("win.bak") == @FALSE Then FileCopy("win.ini",
            "win.bak", @FALSE)
        Run("notepad.exe", "win.ini")


       FileCopy (from-list, to-file, warning)
       Copies files.

       If warning is @TRUE, WinEdit will pop up a dialog box warning you if
       you are about to overwrite an existing file, and giving you an
       opportunity to change your mind.  If warning is @FALSE, it will
       overwrite existing files with no warning.





       Example:
        FileCopy("cmdpost.cpm", "*.sav", @TRUE)
        Run("notepad.exe", "cmdpost.cpm")

       The asterisk (*) is a wildcard character, which matches any letter or
       group of letters in a file name.  In this case, it will cause
       CMDPOST.CPM to be copied as CMDPOST.SAV.


       FileDelete (file-list)
       Deletes files.

       Example:
        If FileExist("win.bak") == @TRUE Then FileDelete("win.bak")


       FileRename (from-list, to-file)
       Renames files to another set of names.



       We can illustrate the use of these WIL file functions with a typical
       batch file application.  Let's suppose that our word processor saves a
       backup copy of each document, with a BAK extension, but we want a
       larger safety net when editing important files.  We want to keep the
       five most recent versions of the wonderful software manual we're
       writing.  Here's a WIL file to accomplish this:

        If FileExist("WIL.bak") == @TRUE Then Goto backup
        :edit
        Run("winword.exe", "WIL.doc")
        Exit
        :backup
        FileDelete("wil.bk5")
        FileRename("wil.bk4", "wil.bk5)
        FileRename("wil.bk3", "wil.bk4)
        FileRename("wil.bk2", "wil.bk3)
        FileRename("wil.bk1", "wil.bk2)
        FileRename("wil.bak", "wil.bk1)
        Goto edit

       If the file WINBATCH.BAK exists, it means that we have made a change
       to WINBATCH.DOC.  So, before we start editing, we delete the oldest
       backup copy, and perform several FileRename functions, until
       eventually WINBATCH.BAK becomes WINBATCH.BK1.  Notice how the flow of
       control moves to the line labeled :backup, and then back to the line
       labeled :edit, and how we terminate processing with the Exit command.
       If we did not include the Exit command, the batch file would continue
       in an endless loop.

       However, this still isn't quite right.  What would happen if the file
       WINBATCH.BK5 didn't exist?  In the DOS batch language, we would get an
       error message, and processing would continue.  But in WIL, the error
       would be fatal, and cause the batch file to abort:
















       There are two ways that we can handle this.  We could use an If
       FileExist test before every file operation, and test the returned
       value for a @TRUE before proceeding.  But this is clumsy, even with
       such a small batch file, and would become unwieldy with a larger one.




       Handling Errors
       Luckily, there is a WIL system function to help us here: ErrorMode.
       The ErrorMode function determines what happens if an error occurs
       during batch file processing.  Here's the syntax:


       ErrorMode (mode)
       Specifies how to handle errors.


       Parameters:
        "mode" =     @CANCEL, @NOTIFY, or @OFF.

       Returns:
        (integer)    previous error setting.

       Use this command to control the effects of runtime errors.  The
       default is @CANCEL, meaning the execution of the batch file will be
       canceled for any error.

       @CANCEL:  All runtime errors will cause execution to be canceled.  The
       user will be notified which error occurred.

       @NOTIFY:  All runtime errors will be reported to the user, and they
       can choose to continue if it isn't fatal.

       @OFF:  Minor runtime errors will be suppressed. Moderate and fatal
       errors will be reported to the user.  User has the option of
       continuing if the error is not fatal.

       As you can see, the default mode is @CANCEL, and it's a good idea to
       leave it like this.  However, it is quite reasonable to change the
       mode for sections of your batch files where you anticipate errors
       occurring.  This is just what we've done in our modified batch file:





        If FileExist("wil.bak") == @TRUE Then Goto backup
        :edit
        Run("winword.exe", "wil.doc")
        Exit
        :backup
        ErrorMode(@OFF)
        FileDelete("wil.bk5")
        FileRename("wil.bk4", "wil.bk5)
        FileRename("wil.bk3", "wil.bk4)
        FileRename("wil.bk2", "wil.bk3)
        FileRename("wil.bk1", "wil.bk2)
        FileRename("wil.bak", "wil.bk1)
        ErrorMode(@CANCEL)
        Goto edit

       Notice how we've used ErrorMode(@OFF) to prevent errors in the section
       labeled backup: from aborting the batch file, and then used
       ErrorMode(@CANCEL) at the end of the that section to change back to
       the default error mode.  This is a good practice to follow.




       Selection Menus
       So far, whenever we have needed to use a file name, we have hard-coded
       it into our WIL files.  For example:

        Run("notepad.exe", "agenda.txt")

       Naturally, there should be a way to get this information from the user
       "on the fly", so that we wouldn't have to write hundreds of different
       batch files.  And there is a way.  Two ways, actually.  Consider,
       first, a function that we have already seen, AskLine:

        file = AskLine("", "Enter Filename to edit?", "")
        Run("notepad.exe", file)

       This will prompt for a filename, and run Notepad on that file:















       There are only three problems with this approach.  First, the user
       might not remember the name of the file.  Second, the user might enter
       the name incorrectly.  And finally, modern software is supposed to be





       sophisticated and user-friendly enough to handle these things the
       right way.  And WIL certainly can.

       There are two new functions we need to use for our new, improved file
       selection routine: FileItemize and ItemSelect.


       FileItemize (file-list)
       Returns a space-delimited list of files.

       This function compiles a list of filenames and separates the names
       with spaces.  There are several variations we can use:

        FileItemize("*.doc")

       would give us a list of all files in the current directory with a DOC
       extension,

        FileItemize("*.com *.exe")

       would give us a list of all files in the current directory with a COM
       or EXE extension, and

        FileItemize("*.*")

       would give us a list of all files in the current directory.

       Of course, we need to be able to use this list, and for that we use:


       ItemSelect (title, list, delimiter)
       Displays a listbox filled with items from a list you specify in a
       string.  The items are separated in your string by a delimiter
       character.

       This is the function which actually displays the list box.  Remember
       that FileItemize returns a file list delimited by spaces, which would
       look something like this:

          FILE1.DOC FILE2.DOC FILE3.DOC

       When we use ItemSelect, we need to tell it that the delimiter is a
       space.  We do this as follows:

        textfiles = FileItemize("*.doc *.txt")
        yourfile = ItemSelect("Select file to edit", textfiles, " ")
        Run("notepad.exe", yourfile)























       First, we use FileItemize to build a list of filenames with DOC and
       TXT extensions.  We assign this list to the variable textfiles.  Then,
       we use the ItemSelect function to build a list box, passing it the
       variable textfiles as its second parameter.  The third parameter we
       use for ItemSelect is simply a space with quote marks around it; this
       tells ItemSelect that the variable textfiles is delimited by spaces.
       Note that this is different from the null string that we've seen
       earlier -- here, you must include a space between the quote marks.
       Finally, we assign the value returned by ItemSelect to the variable
       yourfile, and run Notepad using that file.

       In the list box, if the user presses Enter or clicks on the OK button
       without a file being highlighted, ItemSelect returns a null string.
       If you want, you can test for this condition:

        textfiles = FileItemize("*.doc *.txt")
        :retry
        yourfile = ItemSelect("Select file to edit", textfiles, " ")
        If yourfile == "" Then Goto retry
        Run("notepad.exe", yourfile)

       DirItemize (dir-list)
       Returns a space-delimited list of directories.

       This function is similar to FileItemize, but instead of returning a
       list of files, it returns a list of directories.  Remember we said
       that FileItemize only lists files in the current directory.  Often, we
       want to be able to use files in other directories as well.  We can do
       this by first letting the user select the appropriate directory, using
       the DirItemize and ItemSelect combination:

        DirChange("\")
        subdirs = DirItemize("*")
        targdir = ItemSelect("Select dir", subdirs, " ")
            DirChange(targdir)
        files = FileItemize("*.*")
        file = ItemSelect("Select file", files, " ")
        Run("notepad.exe", file)





       First we change to the root directory.  Then we use DirItemize to get
       a list of all the subdirectories off of the root directory.  Next, we
       use ItemSelect to give us a list box of directories from which to
       select.  Finally, we change to the selected directory, and use
       FileItemize and ItemSelect to pick a file.

       Although this batch file works, it needs to be polished up a bit.
       What happens if the file we want is in the \WINDOWS\BATCH directory?
       Our batch file doesn't go more than one level deep from the root
       directory.  We want  to continue down the directory tree, but we also
       need a way of telling when we're at the end of a branch.  As it
       happens, there is such a way: DirItemize will return a null string if
       there are no directories to process.  Given this knowledge, we can set
       up a loop to test when we are at the lowest level:

        DirChange("\")
        :getdir
        subdirs = DirItemize("*")
        If subdirs == "" Then Goto getfile
        targdir = ItemSelect("Select dir (OK = curr)", subdirs, " ")
        If targdir == "" Then Goto getfile
        DirChange(targdir)
        Goto getdir
        :getfile
        files = FileItemize("*.*")
        file = ItemSelect("Select file", files, " ")
        If file == "" Then Goto getfile
        Run("notepad.exe", file)

       After we use the DirItemize function, we test the returned value for a
       null string.  If we have a null string, then we know that the current
       directory has no subdirectories, and so we proceed to select the
       filename from the current directory (Goto getfile) .  If, however,
       DirItemize returns a non-blank list, then we know that there is, in
       fact, at least one subdirectory.  In that case, we use ItemSelect to
       present the user with a list box of directories.  Then, we test the
       value returned by ItemSelect.  If the returned value is a null string,
       it means that the user did not select a directory from the list, and
       presumably wants a file in the current directory.  We happily oblige
       (Goto getfile).  On the other hand, a non-blank value returned by
       ItemSelect indicates that the user has selected a subdirectory from
       the list box.  In that case, we change to the selected directory, and
       loop back to the beginning of the directory selection routine (Goto
       getdir).  We continue this process until either (a) the user selects a
       directory, or (b) there are no directories left to select.
       Eventually, we get to the section of the batch file labeled :getfile.




       Nicer Display Boxes
       Have you tried displaying long messages, and found that WIL didn't
       wrap the lines quite the way you wanted?  Here are a couple of tricks.


       Num2Char (integer)
       Converts a number to its character equivalent.





       We want to be able to insert a carriage return/line feed combination
       at the end of each line in our output, and the Num2Char function will
       let us do that.  A carriage return has an ASCII value of 13, and a
       line feed has an ASCII value of 10 (don't worry if you don't
       understand what this sentence means).  To be able to use these values,
       we must convert them to characters, as follows:

        cr = Num2Char(13)
        lf = Num2Char(10)

       Now, we need to be able to place the variables cr and lf in our
       message.  For example, let's say we want to do this:

        Message("", "This is line one This is line two")

       If we just inserted the variables into the string, as in:

        cr = Num2Char(13)
        lf = Num2Char(10)
        Message("", "This is line one cr lf This is line two")

       we would not get the desired effect.  WIL would simply treat them as
       ordinary text:












       However, WIL does provide us with a method of performing variable
       substitution such as this, and that is by delimiting the variables
       with percentage signs (%).  If we do this:

        cr = Num2Char(13)
        lf = Num2Char(10)
        Message("", "This is line one %cr% %lf%This is line two")

       we will get what we want:





       Note that there is no space after %lf%; this is so that the second
       line will be aligned with the first line (every space within the
       delimiting quote marks of a string variable is significant).

       Now, wouldn't it be convenient if we could combine cr and lf into a
       single variable?  We can.


       StrCat (string[, string]...)
       Concatenates strings together.

       The StrCat function lets us combine any number of string constants
       and/or string variables.  Here's how we combine the variables cr and
       lf into the single variable crlf:

        crlf = StrCat(cr, lf)

       Note that the strings to be concatenated are separated by commas,
       within the parentheses.  Now, we can rewrite our example, as follows:

        cr = Num2Char(13)
        lf = Num2Char(10)
        crlf = StrCat(cr, lf)
        Message("", "This is line one %crlf%This is line two")

       If we wanted to re-use this message a number of times, it would be
       quite convenient to use the StrCat function to make a single variable
       out of it:

        cr = Num2Char(13)
        lf = Num2Char(10)
        crlf = StrCat(cr, lf)
        line1 = "This is line one"
        line2 = "This is line two"
        mytext = StrCat(line1, crlf, line2)
        Message("", mytext)



       Even Nicer Display Boxes
       For fancy dialog boxes, complete with all the bells and whistles, see
       the separate manual section on the DialogBox function (pg. 185).




       Running DOS Programs
       WIL can run DOS programs, just like it runs Windows programs:

        DirChange("c:\game")
        Run("scramble.exe", "")

       If you want to use an internal DOS command, such as DIR or TYPE, you
       can do so by running the DOS command interpreter, COMMAND.COM, with
       the /c program parameter, as follows:

        Run("command.com", "/c type readme.txt")






       Everything that you would normally type on the DOS command line goes
       after the /c in the second parameter.  Here's another example:

        Run("command.com", "/c type readme.txt | more")

       These examples assume that COMMAND.COM is in a directory on your DOS
       path.  If it isn't, you could specify a full path name for it:

        Run("c:\command.com", "/c type readme.txt | more")

       Or, better still, you could use the WIL Environment function.


       Environment (env-variable)
       Gets a DOS environment variable.

       Since DOS always stores the full path and filename of the command
       processor in the DOS environment variable COMSPEC, it is an easy
       matter to retrieve this information:

        coms = Environment("COMSPEC")

       and use it in our batch file:

        coms = Environment("COMSPEC")
        Run(coms, "/c type readme.txt")

       To get a DOS window, just run COMMAND.COM with no parameters:

        coms = Environment("COMSPEC")
        Run(coms, "")



       Sending Keystrokes to Programs
       Here we come to one of the most useful and powerful features of WIL:
       the ability to send keystrokes to Windows programs, just as if you
       were typing them directly from the keyboard.


       SendKey (character-codes)
       Sends keystrokes to the active application.

       This is an ideal way to make the computer automatically type the
       keystrokes that you enter every time you start a certain program.  For
       example, to start up Notepad and have it prompt you for a file to
       open, you would use:

        Run("notepad.exe", "")
        SendKey("!FO")

       The parameter you specify for SendKey is the string that you want sent
       to the program.  This string consists of standard characters, as well
       as some special characters which you will find listed under the entry
       for SendKey in the WIL Function Reference (pg. 145).  In the example
       above, the exclamation mark (!) stands for the Alt key, so !F is the





       equivalent of pressing and holding down the Alt key while
       simultaneously pressing the F key.  The O in the example above is
       simply the letter O, and is the same as pressing the O key by itself:















       Here's another example:

        RunZoom("sol.exe", "")
        SendKey("!GC{RIGHT}{SP}~")

       This starts up Solitaire, brings up the Game menu (!G), and selects
       Deck (C) from that menu:













       Then it moves the cursor to the next card back style on the right
       ({RIGHT}), selects that card back ({SP}), and then selects OK (~).







       And voila!  A different card design every time you play!




       Our Completed WIL File
       Here is the final working version of the SOLITARE.WBT file that we've
       slowly been building throughout this tutorial:

        ; solitare.wbt
        mins = AskLine("Solitaire", "How many minutes do you want to
            play?", "")
        If WinExist("Solitaire") == @TRUE Then Goto activate
        RunZoom("sol.exe", "")
        Goto loaded
        :activate
        WinActivate("Solitaire")
        WinZoom("Solitaire")
        :loaded
        SendKey("!GC{RIGHT}{SP}~")
        goal = mins * 60
        timer = 0
        :moretime
        remain = goal - timer
        WinTitle("Solitaire", "Solitaire (%remain% seconds left)")
        Delay(10)
        timer = timer + 10
        If WinExist("Solitaire") == @FALSE Then Exit
        If timer < goal Then Goto moretime
        Beep
        WinClose("Solitaire")
        Message("Time's up", "Get back to work!")

       It incorporates many of the concepts that we've discussed so far, as
       well as using some arithmetic (*, -, +) and relational (<) operators
       that are covered in the section on the WIL Language (pg. 1).

       It can also be improved and customized in a number of ways.

       If you can understand and follow the structures and processes
       illustrated in this sample file, and can begin to incorporate them
       into your own WIL files, you are well on your way to becoming a true
       WIL guru!






                                    WIL LANGUAGE




       **Menu Structure
       Menus are defined in a menu file.  Each menu file consists of one or
       more lines of menu statements.  Each line is terminated with a
       carriage return / line feed (CRLF) combination and can be up to 256
       characters long.

       There are two main parts of a menu file:

       The first section, which is optional, is the initialization code.
       This section is executed once when the menu is first loaded and run.
       It's located before the first menu item declaration.

       The remainder of the menu file consists of menu item titles and their
       associated statements.  The code under each menu title is executed
       when the corresponding menu item is selected.  Execution begins at the
       first statement under a menu item and continues up to the definition
       of the next item.




       **Menu Items
       Menu titles can consist of letters, digits, spaces, punctuation marks;
       in fact any displayable ANSI characters your text editor can create.

       There are special characters you can use to modify the appearance of
       items in the menus.

       &    Causes the following character to be underlined in the menu item.
       The user can select the item by pressing the ALT key with the
       character instead of using the mouse.

       |  In a main menu, puts this item on a new line.
       |  In a dropdown menu, this item starts a new column.
       _  Used to create a horizontal bar (in dropdown menus only).

       Most WIL commands carry out functions based on your menu selections.
       However there are a few functions (summarized on pg. Error! Bookmark
                                                            Error! Bookmark
                                                            Error! Bookmark
       not defined.
       not defined.
       not defined.) that can alter the characteristics of the menu titles
       themselves.  For instance you can put a checkmark next to a menu, or
       disable and gray it.

       In order to identify a menu item within a WIL statement, each menu
       item you define has an associated menu name.  The menu name is built
       using only the letters and digits that make up the menu title.  Menu
       names are case-insensitive; you don't have to worry about how the
       actual menu title is capitalized in order to identify it.

       For menu items in a popup menu, the menu name consists of its parent
       menu's name, plus the popup menu item's name concatenated at the end.





       These menu names are valid as soon as the menu file is loaded, so you
       can use the menu management functions in the initialization code
       before the menus even appear.

       Example:
            PW=AskLine ("","Enter your password:", "")
            ;assuming the resident guru's pw is already in WIN.INI:
            RealPW = IniRead ("Our Company", "Tech Guru PW", "")
            Terminate (PW==RealPW, "Access", "You have FULL access")

            MenuChange("SystemUtilitiesCleanupDir",  @DISABLE)
            MenuChange("SystemUtilitiesEditBatFiles",@DISABLE)
            MenuChange("SystemUtilitiesEditWinIni",  @DISABLE)
            Message ("Access", "You have LIMITED access")

        &System Utilities  ;name = "SystemUtilities"
         &Cleanup Dir      ;name = "SystemUtilitiesCleanupDir"
            ...
         &Edit BAT Files...;name = "SystemUtilitiesEditBatFiles"
            ...
         &Edit WIN.INI     ;name = "SystemUtilitiesEditWinIni"
            ...



       Language Components
       WIL statements are constructed from constants, variables, operators,
       functions, commands, and comments.

       Each line in a WIL program can be up to 255 characters long.




       Constants
       The programming language supports both integer and string constants.


       Integer Constants
       Integer constants are built from the digits 0 through 9.  They can
       range in magnitude from negative to positive 231 -1  (approximately
       two billion).  Constants larger than these permissible magnitudes will
       produce unpredictable results.

       Examples of integer constants:

        1
        -45
        377849
        -1999999999

       String Constants
       String constants are comprised of displayable characters bounded by
       quote marks.  You can use double quotes ("), single quotes ('), or
       back quotes (`) to enclose a string constant, as long as the same type
       of quote is used to both start and end it.  If you need to embed the





       delimiting quote mark inside the string constant, use the delimiting
       quote mark twice.

       Examples of string constants:

        "a"
        `Betty Boop`
        "This constant has an embedded "" mark"
        'This constant also has an embedded " mark'

       Predefined Constants
       The programming language has a number of built-in integer constants
       that can be used for various purposes.  These start with the @-sign,
       and are case-insensitive (although we prefer to use ALL CAPS).

       Some predefined constants:

          @FALSE                              @TILE
          @NO                                 @TRUE
          @STACK                              @YES



       A list of all the predefined constants can be found in Appendix A (pg.
       185).




       Identifiers
       Identifiers are the names supplied for variables, functions, and
       commands in your program.

       An identifier is a sequence of one or more letters or digits that
       begins with a letter.  Identifiers may have up to 30 characters.

       All identifiers are case insensitive.  Upper- and lowercase characters
       may be mixed at will inside variable names, commands or functions.

       For example, these statements all mean the same thing:

        AskLine(MyTitle, Prompt, Default)
        ASKLINE(MYTITLE, PROMPT, DEFAULT)
        aSkLiNe(MyTiTlE, pRoMpT, dEfAuLt)



       Variables
       A variable may contain an integer, a string, a list, or a string
       representing an integer.  Automatic conversions between integers and
       strings are performed as a matter of course during execution.

       If a function requires a string parameter and an integer parameter is
       supplied, the variable will be automatically modified to include the
       representative string.





       If a function requires an integer parameter and a string parameter is
       supplied, an attempt will be made to convert the string to an integer.
       If it does not convert successfully, an error will result.




       Keywords
       "Keywords" are the predefined identifiers that have special meaning to
       the programming language.  These cannot be used as variable names.

       WIL keywords consist of the functions, commands, and predefined
       constants.

       Some examples of reserved keywords:

          Beep
          DirChange
          @Yes
          FileCopy



       Operators
       The programming language operators take one operand ("unary
       operators") or two operands ("binary operators").

       Unary operators (integers only):
          -      Arithmetic Negation (Two's complement)
          +      Identity (Unary plus)
          ~      Bitwise Not.  Changes each 0 bit to 1, and vice-versa.
          !      Logical Not.  Produces 0 (@FALSE) if the operand is nonzero,
                 else 1 (@TRUE) if the operand is zero.


       Binary arithmetic operators (integers only):
          *      Multiplication
          /      Division
          mod    Modulo
          +      Addition
          -      Subtraction
          <<     Left Shift
          >>     Right Shift
          &      Bitwise And
          |      Bitwise Or
          ^      Bitwise Exclusive Or  (XOR)
          &&     Logical And
          | |    Logical Or


       Binary relational operators (integers and strings):
          >      Greater-than
          >=     Greater-than or equal
          <      Less-than
          <=     Less-than or equal
          ==     Equality
          != or <>    Inequality





       Assignment operator (integers and strings):
          =      Assigns evaluated result of an expression to a variable




       Precedence and evaluation order
       The precedence of the operators affect the evaluation of operands in
       expressions.  Operands associated with higher-precedence operators are
       evaluated before the lower-precedence operators.

       The table below shows the precedence of the operators.  Where
       operators have the same precedence, they are evaluated from left to
       right.

       Operator            Description
          ( )              Parenthetical grouping
          ~ ! - +          Unary operators
          * / mod          Multiplication & Division
          + -              Addition & Subtraction
          <<  >>           Shift operators
          < <= == >= > != <>    Relational operators
          & ^ |            Bit manipulation operators
          && ||            Logical operators



       Comments
       A comment is a sequence of characters that are ignored when processing
       a command.  A semicolon (not otherwise part of a string constant)
       indicates the beginning of a comment.

       All characters to the right of the semicolon are considered comments,
       and are ignored.

       Blank lines are also ignored.

       Examples of comments:
        ; This is a comment
        abc = 5  ; This is also a comment



       Statements

       Assignment Statements
       Assignment statements are used to set variables to specific or
       computed values.  Variables may be set to integers or strings.

       Examples:
        a = 5
        value = Average(a, 10, 15)
        location = "Northern Hemisphere"
        world = StrCat(location, " ", "Southern Hemisphere")






       Control Statements
       Control statements are generally used to execute system management
       functions and consist of a call to a command without assigning any
       return values.

       Examples:
        Exit
        Yield



       Substitution
       The batch language has a powerful substitution feature which inserts
       the contents of a string variable into a statement before the line is
       parsed.

       To substitute the contents of a variable in the statement, simply put
       a percent-sign (%) on both sides of the variable name.

       Examples:
        mycmd = "DirChange('c:\')"   ;set mycmd to a command
        %mycmd%                 ;execute the command

       Or consider this one:

        IniWrite("PC", "User", "Richard")
        ...
        name = IniRead("PC", "User", "somebody")
        message("", "Thank you, %name%")

       will produce this message box:












       The variable substitution feature can be used to simulate an "array"
       of strings.  For example, if you wanted to read the lines contained in
       a file into an array of variables named line1 through line# (where #
       is the line number of the last line in the file), and then write them
       to a new file in reverse order, you could do so as follows:





        handle = FileOpen("c:\config.sys", "READ")
        num = 0
        :readnext
        num = num + 1
        line%num% = FileRead(handle)
        If line%num% != "*EOF*" Then Goto readnext
        FileClose(handle)
        handle = FileOpen("c:\config.rev", "WRITE")
        :writenext
        num = num - 1
        FileWrite(handle, line%num%)
        If num > 1 Then Goto writenext
        FileClose(handle)
        Message("Processing complete", "CONFIG.REV created")


       To put a single percent-sign (%) on a source line, specify a double
       percent sign(%%).  This is required even inside quoted strings.

       Note:  The length of a line, after any substitution occurs, may not
       exceed 255 characters.




       **Language Directives
       A "language directive" is a command to the WIL interpreter, as opposed
       to a menu statement.  These begin with a pound-sign ("#") in column 1.

       Currently there is only one directive recognized by Command Post:
       #NextFile. This directive tells the WIL interpreter to append another
       .CPM file to the current one before building the menus.  You can
       append only one extra menu file in this way.




       Function Parameters
       Most of the functions and commands in the language require parameters.
       These come in several types:

          Integer
          String
          List
          Variable name


       The interpreter performs automatic conversions between strings and
       integers, so in general you can use them interchangeably.

       Integer parameters may be any of the following:

          An integer (i.e. 23)
          A string representing an integer (i.e. "23")
          A variable containing an integer
          A variable containing a string representing an integer





       String parameters may be any of the following:

          A string
          An integer
          A variable containing a string
          A variable containing a list
          A variable containing an integer




       Error Handling
       There are three types of errors that can occur while processing a
       batch file:  Minor, Moderate, and Fatal.  What happens when an error
       occurs depends on the current error mode, which is set with the
       ErrorMode function.

       There are three possible modes you can specify:

       @CANCEL
          User is notified when any error occurs, and then the batch file is
          canceled.  This is the default.

       @NOTIFY
          User is notified when any error occurs, and has option to continue
          unless the error is fatal.

       @OFF
          User is only notified if the error is moderate or fatal.  User has
          option to continue unless the error is fatal.

       The function LastError returns the code of the most-recent error
       encountered during the current batch file.

       Minor errors are numbered from 1000 to 1999.
       Moderate errors are numbered from 2000 to 2999.
       Fatal errors are numbered from 3000 to 3999.

       Error handling is reset to @CANCEL at the start of each WIL program.




       The Functions & Statements



       Inputting Information
       AskLine (title, prompt, default)
          Lets user enter a line of information.

       AskPassword (title, prompt)
          Prompts the user for a password.

       AskYesNo (title, question)
          Lets user choose from Yes, No, or Cancel.





       ItemSelect (title, list, delimiter)
          Chooses an item from a listbox.

       TextBox (title, filename)
          Fills a listbox from text strings in a file.

       TextSelect (title, list, delimiter)
          Allows the user to choose an item from an unsorted listbox.




       Displaying Information
       Beep
          Beeps at the user.

       DialogBox (title, WDG file)
          Pops up a Windows dialog box defined by the WDG template file.

       Display (seconds, title, text)
          Momentarily displays a string.

       Message (title, text)
          Displays text in a message box.

       Pause (title, text)
          Displays text in a message box.

       TextBox (title, filename)
          Fills a listbox from text strings in a file.

       TextSelect (title, list, delimiter)
          Allows the user to choose an item from an unsorted listbox.




       File Management
       FileAppend (from-list, to-file)
          Appends one or more files to another file.

       FileAttrGet (filename)
          Returns file attributes.

       FileAttrSet (file-list, settings)
          Sets file attributes.

       FileClose (filehandle)
          Closes a file.

       FileCopy (from-list, to-file, warning)
          Copies files.

       FileDelete (file-list)
          Deletes files.





       FileExist (filename)
          Determines if a file exists.

       FileExtension (filename)
          Returns extension of file.

       FileItemize (file-list)
          Builds a list of files.

       FileLocate (filename)
          Finds a file within the current DOS path.

       FileMove (from-list, to-file, warning)
          Moves files to another set of pathnames.

       FileOpen (filename, open-type)
          Opens a STANDARD ASCII (only) file for reading or writing.

       FilePath (filename)
          Returns path of file.

       FileRead (filehandle)
          Reads data from a file.

       FileRename (from-list, to-file)
          Renames files to another set of names.

       FileRoot (filename)
          Returns root of file.

       FileSize (file-list)
          Adds up the total size of a set of files.

       FileTimeGet (filename)
          Returns file date and time.

       FileTimeTouch (file-list)
          Sets file(s) to current time.

       FileWrite (filehandle,output-data)
          Writes data to a file.

       IniDelete (section, keyname)
          Removes a line or section from WIN.INI.

       IniDeletePvt (section, keyname, filename)
          Removes a line or section from a private INI file.

       IniItemize (section)
          Lists keywords or sections in WIN.INI.

       IniItemizePvt (section, filename)
          Lists keywords or sections in a private INI file.

       IniRead (section, keyname, default)
          Reads a string from the WIN.INI file.





       IniReadPvt (section, keyname, default, filename)
          Reads a string from a private INI file.

       IniWrite (section, keyname, string)
          Writes a string to the WIN.INI file.

       IniWritePvt (section, keyname, data, filename)
          Writes a string to a private INI file.




       Directory Management
       DirChange ([d:]path)
          Changes the current directory.

       DirGet ( )
          Returns the current directory path.

       DirHome ( )
          Returns the initial directory path.

       DirItemize (dir-list)
          Builds a list of directories.

       DirMake ([d:]path)
          Creates a new directory.

       DirRemove ([d:]path)
          Removes an existing directory.

       DirRename ([d:]oldpath, [d:]newpath)
          Renames a directory.

       DirWindows (request#)
          Returns the name of the Windows or Windows System directory.




       Disk Drive Management
       DiskFree (drive-list)
          Returns the amount of free space on a set of drives.

       DiskScan (request#)
          Returns list of drives.

       LogDisk (drive)
          Changes the logged disk drive.




       Window Management
       AppExist (program-name)
          Tells if an application is running.





       AppWaitClose (program-name)
          Suspends WIL program execution until a specified application has
          been closed.

       IconArrange ( )
          Rearranges icons.

       WinActivate (partial-winname)
          Makes an application window the active window.

       WinArrange (style)
          Arranges all running application windows on the screen.

       WinClose (partial-winname)
          Closes an application window.

       WinCloseNot (partial-winname [, partial-winname...])
          Closes all application windows except those specified.

       WinExeName (partial-winname)
          Returns the name of the executable file which created a specified
          window.

       WinExist (partial-winname)
          Tells if window exists.

       WinGetActive ( )
          Gets the title of the active window.

       WinHide (partial-winname)
          Hides an application window.

       WinIconize (partial-winname)
          Turns an application window into an icon.

       WinItemize ( )
          Lists all the main windows currently running.

       WinName ( )
          Returns the name of the window calling the WIL Interpreter.

       WinPlace (x-ul, y-ul, x-br, y-br, partial-winname)
          Changes the size and position of an application window on the
          screen.

       WinPlaceGet (win-type, partial-winname)
          Returns window coordinates.

       WinPlaceSet (win-type, partial-winname, position-string)
          Sets window coordinates.

       WinPosition (partial-winname)
          Returns window position.

       WinShow (partial-winname)
          Shows a currently-hidden application window.





       WinState (partial-winname)
          Returns the current state of a window.

       WinTitle (partial-winname, new-winname)
          Changes the title of an application window.

       WinWaitClose (partial-winname)
          Waits until an application window is closed.

       WinZoom (partial-winname)
          Maximizes an application window to full-screen.




       Program Management
       Run (program-name, parameters)
          Runs a program as a normal window.

       RunHide (program-name, parameters)
          Runs a program in a hidden window.

       RunHideWait (program-name, parameters)
          Runs a program in a hidden window, and waits for it to close.

       RunIcon (program-name, parameters)
          Runs a program as an icon.

       RunIconWait (program-name, parameters)
          Runs a program as an icon, and waits for it to close.

       RunWait (program-name, parameters)
          Runs a program as a normal window, and waits for it to close.

       RunZoom (program-name, parameters)
          Runs a program in a maximized window.

       RunZoomWait (program-name, parameters)
          Runs a program in a maximized window, and waits for it to close.




       String Handling
       Char2Num (string)
          Returns the ANSI code of a string's first character.

       IsNumber (string)
          Determines if a string represents a valid number.

       ItemCount (list, delimiter)
          Returns the number of items in a list.

       ItemExtract (select, list, delimiter)
          Returns the selected item from a list.





       ItemInsert (item, index, list, delimiter)
          Adds an item to a list.

       ItemLocate (item, list, delimiter)
          Returns the position of an item in a list.

       ItemRemove (index, list, delimiter)
          Removes an item from a list.

       ItemSort (list, delimiter)
          Sorts a list.

       Num2Char (number)
          Converts a number to the ANSI character it represents.

       ParseData (string)
          Parses the passed string, just like passed parameters are parsed.

       StrCat (string[, string...])
          Concatenates strings together.

       StrCmp (string1, string2)
          Compares two strings.

       StrFill (string, string-length)
          Builds a string from a repeated smaller string.

       StrFix (base-string, padding-string, length)
          Pads or truncates a string to a fixed length.

       StriCmp (string1, string2)
          Compares two strings, ignoring their case.

       StrIndex (main-str, sub-str, start, direction)
          Locates a string within a larger string.

       StrLen (string)
          Returns the length of a string

       StrLower (string)
          Converts a string to all lower-case characters.

       StrReplace (string, old, new)
          Replaces all occurances of a substring with another.

       StrScan (main-str, delims, start, direction)
          Finds an occurrence of one or more delimiter characters in a
          string.

       StrSub (string, start, length)
          Returns a substring from within a string.

       StrTrim (string)
          Trims leading and trailing blanks from a string.

       StrUpper (string)
          Converts a string to all upper-case characters.








       Arithmetic Functions
       Abs (number)
          Returns the absolute value of a number.

       Average (num [, num...])
          Returns the average of a list of numbers.

       Max (num [, num...])
          Determines the highest number in a list.

       Min (num [, num...])
          Determines the lowest number in a list.

       Random (max)
          Generates a positive random number.




       Clipboard Handling
       ClipAppend (string)
          Appends a string to the end of the Clipboard.

       ClipGet ( )
          Returns the Clipboard contents into a string.

       ClipPut (string)
          Replaces the Clipboard contents with a string.




       Process Control
       Call (filename, parameters)
          Calls another WIL batch file as a subroutine.

       Debug (mode)
          Turns Debug mode on or off.

       Delay (seconds)
          Pauses batch file execution.

       Drop (var [, var...])
          Deletes variables to recover their memory.

       Else statement
          Continues a previous If statement.

       EndSession ( )
          Ends the current Windows session.

       ErrorMode (mode)
          Sets what happens in the event of an error.





       Exclusive (mode)
          Controls whether or not other Windows program will get any time to
          execute.

       Execute statement
          Directly executes a WIL statement.

       Exit
          Unconditionally ends a WIL program.

       Goto label
          Changes the flow of control in a batch file.

       If condition Then statement
          Conditionally performs a function.

       IgnoreInput (mode)
          Turns off hardware input to windows.

       IsDefined (variable)
          Determines if a variable is currently defined.

       IsKeyDown (key-codes)
          Tells about keys/mouse.

       LastError ( )
          Returns the last error encountered.

       Return
          Returns from a Call to the calling program.

       SKDebug (mode)
          Controls how SendKey works

       Terminate
          Conditionally ends a WIL program.

       Then statement
          Continues a previous If statement.

       WaitForKey
          Waits for a specific key to be pressed.

       Yield
          Pauses batch file processing so other applications can process some
          messages.




       Miscellaneous Functions
       IntControl (request#, p1, p2, p3, p4)
          Internal control functions.

       SendKey (character-codes)
          Sends keystrokes to the active application.





       SnapShot (request#)
          Takes a snapshot of the screen and pastes it to the clipboard.

       WallPaper (bmp-name, tile)
          Changes the Windows wallpaper.

       WinParmSet (request#, new-value, ini-control)
          Sets system information.




       System Information
       DateTime ( )
          Returns the current date and time.

       DOSVersion (level)
          Returns the version numbers of the current version of DOS.

       Environment (env-variable)
          Returns the value of a DOS environment variable.

       IsLicensed ( )
          Tells if the calling application is licensed.

       MouseInfo (request#)
          Returns assorted mouse information.

       Version ( )
          Returns the version of the parent program currently running.

       VersionDLL ( )
          Returns the version of the WIL Interpreter currently running.

       WinConfig ( )
          Returns WIN3 mode flags.

       WinMetrics (request#)
          Returns Windows system information.

       WinParmGet (request#)
          Returns system information.

       WinParmSet (request#, new-value, ini-control)
          Sets system information.

       WinResources (request#)
          Returns information on available memory and resources.

       WinVersion (level)
          Returns the version of Windows that is currently running.








       DDE Functions
       DDEExecute (channel, command string)
          Sends commands to a DDE server application.

       DDEInitiate (app name, topic name)
          Opens a DDE channel.

       DDEPoke (channel, item name, item value)
          Sends data to a DDE server application.

       DDERequest (channel, item name)
          Gets data from a DDE server application.

       DDETerminate (channel)
          Closes a DDE channel.

       DDETimeout (value)
          Sets the DDE timeout value.




       Network Functions
       NetAddCon (net-path, password, local-name)
          Connects network resources to imaginary local disk drives or
          printer ports.

       NetAttach (server-name)
          Attaches to a network file server.

       NetBrowse (request#)
          Displays a network dialog box allowing the user to select a network
          resource.

       NetCancelCon (name, force)
          Breaks a network connection.

       NetDetach (server-name)
          Detaches from a network file server.

       NetDialog ( )
          Brings up the network driver's dialog box.

       NetGetCaps (request#)
          Returns information on network capabilities.

       NetGetCon (local-name)
          Returns the name of a connected network resource.

       NetGetUser ( )
          Returns the name of the user currently logged into the network.

       NetLogin(server-name, user-name, password)
          Performs a network login.





       NetLogout(server-name)
          Performs a network logout.

       NetMapRoot(local-name, net-path)
          Maps a local drive to a network resource.

       NetMemberGet(server-name, group-name)
          Determines whether the current user is a member of a specific
          group.

       NetMemberSet(server-name, group-name)
          Sets the current user as a member of a group.

       NetMsgAll(server-name, message)
          Broadcasts a message to all users on the network.

       NetMsgSend(server-name, user-name, message)
          Sends a message to a specific user on the network.




       Multimedia Functions
       PlayMedia (command-string)
          Controls multimedia devices.

       PlayMidi (filename, mode)
          Plays a MID or RMI sound file.

       PlayWaveForm (filename, mode)
          Plays a WAV sound file.

       Sounds (request#)
          Turns sounds on or off.




       Menu Management
       CurrentFile ( )
          Returns the selected filename.

       IsMenuChecked (menuname)
          Determines if a menu item has a checkmark next to it.

       IsMenuEnabled (menuname)
          Determines if a menu item has been enabled.

       MenuChange (menuname, flags)
          Checks, unchecks, enables, or disables a menu item.






                                         WIL
                                      FUNCTION
                                      REFERENCE




       Introduction
       The WIL programming language consists of more than 150 functions and
       commands, which we describe in detail in this section.

       We use a shorthand notation to indicate the syntax of the functions.

       Function names and other actual characters you type are in boldface.
       Optional parameters are enclosed in square brackets "[ ]".  When a
       function takes a variable number of parameters, the variable parts
       will be followed by ellipses ("...").

       Take, for example, string concatenation:

       StrCat (string[, string...])

       This says that the StrCat function takes at least one string
       parameter.  Optionally, you can specify more strings to concatenate.
       If you do, you must separate the strings with commas.

       For each function and command, we show you the Syntax, describe the
       Parameters (if any), the value it Returns (if any), a description of
       the function, Example code (shown in Courier type), and related
       functions you may want to See Also.



       Items marked [*M] are available only in menu script usages (such as
       Command Post and File Commander).



       WIL Interpreter is a generic term which refers both to Command Post
       and to WIL.

       WIL program is a generic term which refers both to the script for a
       menu item and to a standalone batch file.



       (i) indicates an integer parameter or return value.

       (s) indicates a string parameter or return value.




       Abs
       Returns the absolute value of a number.






       Syntax:
        Abs (integer)

       Parameters:
        (i) integer  integer whose absolute value is desired.

       Returns:
        (i)          absolute value of integer.

       This function returns the absolute (positive) value of the integer
       which is passed to it, regardless of whether that integer is positive
       or negative.


       Example:
        dy = Abs(y1 - y2)
        Message("Years", "There are %dy% years 'twixt %y1% and %y2%")


       See Also:
          Average, IsNumber, Max, Min




       AppExist
       Tells if an application is running.


       Syntax:
        AppExist (program-name)

       Parameters:
        (s) program-name   name of a Windows EXE or DLL file.

       Returns:
        (i)          @TRUE if the specified application is running;
                     @FALSE if the specified application is not running.

       Use this function to determine whether a specific Windows application
       is currently running.  Unlike WinExist, you can use AppExist without
       knowing the title of the application's window.

       "Program-name" is the name of a Windows EXE or DLL file, including the
       file extension (and, optionally, a full path to the file).


       Example:
        If AppExist("clock.exe") == @FALSE Then Run("clock.exe", "")


       See Also:
          AppWaitClose, Run, WinExeName, WinExist








       AppWaitClose
       Suspends WIL program execution until a specified application has been
       closed.


       Syntax:
        AppWaitClose (program-name)

       Parameters:
        (s) program-name   name of a Windows EXE or DLL file.

       Returns:
        (i)          @TRUE if the specified application is running;
                     @FALSE if the specified application is not running.

       Use this function to suspend the WIL program's execution until the
       user has finished using a given application and has manually closed
       it.  Unlike WinWaitClose, you can use AppWaitClose without knowing the
       title of the application's window.

       "Program-name" is the name of a Windows EXE or DLL file, including the
       file extension (and, optionally, a full path to the file).


       Example:
        Run("clock.exe", "")
        Display(4, "Note", "Close Clock to continue")
        AppWaitClose("clock.exe")
        Message("Continuing...", "Clock closed")


       See Also:
          AppExist, Delay, RunWait, WinExeName, Yield




       AskLine
       Prompts the user for one line of input.


       Syntax:
        AskLine (title, prompt, default)

       Parameters:
        (s) title    title of the dialog box.
        (s) prompt   question to be put to the user.
        (s) default  default answer.

       Returns:
        (s)          user response.

       Use this function to query the user for a line of data.  The entire
       user response will be returned if the user presses the OK button or





       the Enter key.  If the user presses the Cancel button or the Esc key,
       the processing of the WIL program is canceled.


       Example:
        name = AskLine("Game", "Please enter your name", "")
        game = AskLine("Game", "Favorite game?", "Solitaire")
        message(StrCat(name,"'s favorite game is "), game)

       produces:























       And then, if Richard types "Scramble" and clicks on the OK button:









       See Also:
          AskPassword, AskYesNo, DialogBox, Display, ItemSelect, Message,
          Pause, TextBox, TextSelect




       AskPassword
       Prompts the user for a password.


       Syntax:
        AskPassword (title, prompt)






       Parameters:
        (s) title    title of the dialog box.
        (s) prompt   question to be put to the user.

       Returns:
        (s)          user response.

       Pops up a special dialog box to ask for a password.  An asterisk (*)
       is echoed for each character that the user types; the actual
       characters entered are not displayed.  The entire user response will
       be returned if the user presses the OK button or the Enter key.  If
       the user presses the Cancel button or the Esc key, the processing of
       the WIL program is canceled.


       Example:
        pw = AskPassword("Security check", "Please enter your password")
        If StriCmp(pw, "winguy") != 0 Then Goto nogo
        Run(Environment("COMSPEC"), "")
        Exit
        :nogo
        Pause("Security breach", "Invalid password entered")


       See Also:
          AskLine, AskYesNo, DialogBox




       AskYesNo
       Prompts the user for a Yes or No answer.


       Syntax:
        AskYesNo (title, question)

       Parameters
        (s) title    title of the question box.
        (s) question question to be put to the user.

       Returns:
        (i)          @YES or @NO, depending on the button pressed.

       This function displays a message box with three pushbuttons - Yes, No,
       and Cancel.  If the user presses Cancel, the current WIL program is
       ended, so there is no return value.


       Example:
        q = AskYesNo('Testing', 'Please press "YES"')
        If q == @YES Then Exit
        Display(3, 'ERROR', 'I said press "YES"')

       Produces:















       And then, if the user presses No:







       See Also:
          AskLine, AskPassword, DialogBox, Display, ItemSelect, Message,
          Pause, TextBox




       Average
       Returns the average of a list of numbers.


       Syntax:
        Average (integer [, integer...])

       Parameters:
        (i) integer  integers to get the average of.

       Returns:
        (i)          average of the integers.

       Use this function to compute the mean average of a series of numbers,
       delimited by commas.  This function returns an integer value, so there
       can be some rounding error involved.


       Example:
        avg = Average(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
        Message("The average is", avg)


       See Also:
          Abs, Max, Min, Random




       Beep
       Beeps once.






       Syntax:
        Beep

       Parameters:
        (none)

       Returns:
        (not applicable)


       Use this command to produce a short beep, generally to alert the user
       to an error situation or to get the user's attention.


       Example:
        Beep
        Pause("WARNING!!!", "You are about to destroy data!")


       See Also:
          PlayMedia, PlayMidi, PlayWaveForm, Sounds




       Call
       Calls another WIL batch file as a subroutine.


       Syntax:
        Call (filename, parameters)

       Parameters:
        (s) filename the WIL batch file you are calling (including
                     extension).
        (s) parameters     the parameters to pass to the file, if any, in the
                     form
                     "p1 p2 p3 ... pn".

       Returns:
        (i)          always 0.


       This function is used to pass control temporarily to a secondary WIL
       batch file.  The main WIL program can optionally pass parameters to
       the secondary WIL batch file.  All variables are common (global)
       between the calling program and the called WIL batch file, so that the
       secondary WIL batch file may modify or create variables.  The
       secondary WIL batch file should end with a Return statement, to pass
       control back to the main WIL program.

       If a string of parameters is passed to the secondary WIL batch file,
       it will automatically be parsed into individual variables with the
       names param1, param2, etc., (maximum of nine parameters).  The
       variable param0 will be a count of the total number of parameters in
       the string.






       Example:
        ; MAIN.WBT
        name = AskLine("", "What is your name?", "")
        age = AskLine("", "How old are you?", "")
        valid = @NO
        Call("chek-age.wbt", age)
        If valid == @NO Then Message("", "Invalid age")

        ; CHEK-AGE.WBT
        userage = param1
        really = AskYesNo("", "%name%, are you really %userage%?")
        If really == @NO Then Return
        If (userage > 0) && (userage < 150) Then valid = @YES
        Return


       See Also:
          ParseData, Return




       Char2Num
       Converts the first character of a string to its numeric equivalent.


       Syntax:
        Char2Num (string)

       Parameters:
        (s) string   any text string.  Only the first character will be
                     converted.

       Returns:
        (i)          ANSI character code.

       This function returns the 8-bit ANSI code corresponding to the first
       character of the string parameter.

       Note:  For the commonly-used characters (with codes below 128), ANSI
       and ASCII characters are identical.


       Example:
        ; Show the hex equivalent of entered character
        inpchar = AskLine("ANSI Equivalents", "Char:", "")
        ansi = StrSub(inpchar, 1, 1)
        ansiequiv = Char2Num(InpChar)
        Message("ANSI Codes", "%ansi% => %ansiequiv%")


       See Also:
          IsNumber, Num2Char








       ClipAppend
       Appends a string to the Clipboard.


       Syntax:
        ClipAppend (string)

       Parameters:
        (s) string   text string to add to Clipboard.

       Returns:
        (i)          @TRUE if string was appended;
                     @FALSE if Clipboard ran out of memory.

       Use this function to append a string to the Windows Clipboard.  The
       Clipboard must either contain text data or be empty for this function
       to succeed.


       Example:
        ; The code below will append 2 copies of the
        ; Clipboard contents back to the Clipboard, resulting
        ; in 3 copies of the original contents with a CR/LF
        ; between each copy.
        a = ClipGet()
        crlf = StrCat(Num2Char(13), Num2Char(10))
        ClipAppend(crlf)
        ClipAppend(a)
        ClipAppend(crlf)
        ClipAppend(a)


       See Also:
          ClipGet, ClipPut




       ClipGet
       Returns the contents of the Clipboard.


       Syntax:
        ClipGet ( )

       Parameters:
        (none)

       Returns:
        (s)          Clipboard contents.

       Use this function to copy text from the Windows Clipboard into a
       string variable.





       Note:  If the Clipboard contains an excessively large string a (fatal)
       out of memory error may occur.


       Example:
        ; The code below will convert Clipboard contents to
        ; uppercase
        ClipPut(StrUpper(ClipGet()))
        a = ClipGet()
        Message("UPPERCASE Clipboard Contents", a)


       See Also:
          ClipAppend, ClipPut




       ClipPut
       Copies a string to the Clipboard.


       Syntax:
        ClipPut (string)

       Parameters:
        (s) string   any text string.

       Returns:
        (i)          @TRUE if string was copied;
                     @FALSE if Clipboard ran out of memory.

       Use this function to copy a string to the Windows Clipboard.  The
       previous Clipboard contents will be lost.


       Example:
        ; The code below will convert Clipboard contents to
        ; lowercase
        ClipPut(StrLower(ClipGet()))
        a = ClipGet()
        Message("lowercase Clipboard Contents", a)


       See Also:
          ClipAppend, ClipGet, SnapShot




       CurrentFile [*M]
       Returns the selected filename.


       Syntax:
        CurrentFile ( )






       Parameters:
        (none)

       Returns:
        (s)          currently-selected file's name.

       When the WIL menu shell displays the files in the current directory,
       one of them may be "selected."  This function returns the name of that
       file, if any.

       This is different than a "highlighted" file.  When a file is
       highlighted, it shows up in inverse video (usually white-on-black).
       To find the filenames that are highlighted, see FileItemize.

       Note: This command is not part of the WIL Interpreter package, but is
       documented here because it has been implemented in many of the shell
       or file manager-type applications which use the WIL Interpreter.


       Example:
        ; ask which program to run (default = current file)
        thefile = AskLine("Run It", "Program:", CurrentFile())
        Run(thefile, "")


       See Also:
          DirGet, DirItemize, FileItemize




       DateTime
       Provides the current date and time.


       Syntax:
        DateTime ( )

       Parameters:
        (none)

       Returns:
        (s)          today's date and time

       This function will return the current date and time in a pre-formatted
       string.  The format it is returned in depends on how it is set up in
       the [Intl] section of the WIN.INI file:

       ddd mm/dd/yy hh:mm:ss XX
       ddd dd/mm/yy hh:mm:ss XX
       ddd yy/mm/dd hh:mm:ss XX

       Where:
          ddd is day of the week (e.g. Mon)
          mm  is the month (e.g. 10)
          dd  is the day of the month (e.g. 23)





          yy  is the year (e.g. 90)
          hh  is the hours
          mm  is the minutes
          ss  is the seconds
          XX  is the Day/Night code (e.g. AM or PM)

       Note:  Windows provides even more formatting options than this.

       The WIN.INI file will be examined to determine which format to use.
       You can adjust the WIN.INI file via the [Intl] section of Control
       Panel if the format isn't what you prefer.


       Example:
        ; assuming the current standard is U.S.
        ; (i.e. day  dd/mm/yy hh:mm:ss AM)
        Message("Current Date & Time", DateTime())

       would produce:









       See Also:
          FileTimeGet




       DDEExecute
       Sends commands to a DDE server application.


       Syntax:
        DDEExecute (channel, command string)

       Parameters:
        (i) channel  same integer that was returned by DDEInitiate.
        (s) command string one or more commands to be executed by the server
                     app.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       Use the DDEInitiate function to obtain a channel number.

       In order to use this function successfully, you will need appropriate
       documentation for the server application you wish to access, which
       must provide information on the DDE functions that it supports and the
       correct syntax to use.






       Example:
        Run("wincheck.exe", "TUT")
        channel = DDEInitiate("wincheck", "TUT")
        If channel == 0 Then Goto failed
        result = DDEExecute(channel, '[WriteCheck:p="Shorewood
            Apartments",t=580.00,l="Rent"]')
        DDETerminate(channel)
        WinClose("WinCheck")
        If result == @FALSE Then Goto Failed
        Message("DDE Execute", "Operation complete")
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")


       See Also:
          DDEInitiate, DDEPoke, DDERequest, DDETerminate, DDETimeout




       DDEInitiate
       Opens a DDE channel.


       Syntax:
        DDEInitiate (app name, topic name)

       Parameters:
        (s) app name name of the application (without the EXE extension).
        (s) topic name     name of the topic you wish to access.

       Returns:
        (i)          communications channel.

       This function opens a DDE communications channel with a server
       application.  The communications channel can be subsequently used by
       the DDEExecute, DDEPoke, and DDERequest functions.  You should close
       this channel with DDETerminate when you are finished using it.  If the
       communications channel cannot be opened as requested, DDEInitiate
       returns a channel number of 0.

       You can call DDEInitiate more than once, in order to carry on multiple
       DDE conversations (with multiple applications) simultaneously.

       In order to use this function successfully, you will need appropriate
       documentation for the server application you wish to access, which
       must provide information on the DDE functions that it supports and the
       correct syntax to use.






       Example:
        Run("wincheck.exe", "TUT")
        channel = DDEInitiate("WinCheck", "TUT")
        If channel == 0 Then Goto failed
        output = DDERequest(channel, "GetChecking")
        DDETerminate(channel)
        WinClose("WinCheck")
        If output == "" Then Goto Failed
        Message("Account balance", output)
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")


       See Also:
          DDEExecute, DDEPoke, DDERequest, DDETerminate, DDETimeout




       DDEPoke
       Sends data to a DDE server application.


       Syntax:
        DDEPoke (channel, item name, item value)

       Parameters:
        (i) channel  same integer that was returned by DDEInitiate.
        (s) item name identifies the type of data being sent.
        (s) item value     actual data to be sent to the server.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       Use the DDEInitiate function to obtain a channel number.

       In order to use this function successfully, you will need appropriate
       documentation for the server application you wish to access, which
       must provide information on the DDE functions that it supports and the
       correct syntax to use.


       Example:
        Run("reminder.exe", "")
        channel = DDEInitiate("Reminder", "items")
        If channel == 0 Then Goto failed
        result = DDEPoke(channel, "all", "11/3/92 Misc Remember to vote")
        DDETerminate(channel)
        WinClose("Reminder")
        If result == @FALSE Then Goto Failed
        Message("DDE Poke", "Operation complete")
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")






       See Also:
          DDEExecute, DDEInitiate, DDERequest, DDETerminate, DDETimeout




       DDERequest
       Gets data from a DDE server application.


       Syntax:
        DDERequest (channel, item name)

       Parameters:
        (i) channel  same integer that was returned by DDEInitiate.
        (s) item name identifies the data to be returned by the server.

       Returns:
        (s)          information returned from the server.

       Use the DDEInitiate function to obtain a channel number.

       In order to use this function successfully, you will need appropriate
       documentation for the server application you wish to access, which
       must provide information on the DDE functions that it supports and the
       correct syntax to use.


       Example:
        Run("wincheck.exe", "TUT")
        channel = DDEInitiate("WinCheck", "TUT")
        If channel == 0 Then Goto failed
        output = DDERequest(channel, "GetChecking")
        DDETerminate(channel)
        WinClose("WinCheck")
        If output == "" Then Goto Failed
        Message("Account balance", output)
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")


       See Also:
          DDEExecute, DDEInitiate, DDEPoke, DDETerminate, DDETimeout




       DDETerminate
       Closes a DDE channel.


       Syntax:
        DDETerminate (channel)






       Parameters:
        (i) channel  same integer that was returned by DDEInitiate.

       Returns:
        (i)          always 1.

       This function closes a communications channel that was opened with
       DDEInitiate.

       Example:
        Run("wincheck.exe", "TUT")
        channel = DDEInitiate("WinCheck", "TUT")
        If channel == 0 Then Goto failed
        output = DDERequest(channel, "GetChecking")
        DDETerminate(channel)
        WinClose("WinCheck")
        If output == "" Then Goto Failed
        Message("Account balance", output)
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")


       See Also:
          DDEExecute, DDEInitiate, DDEPoke, DDERequest, DDETimeout




       DDETimeout
       Sets the DDE timeout value.


       Syntax:
        DDETimeout (value)

       Parameters:
        (i) value    DDE timeout time.

       Returns:
        (i)          previous timeout value.

       Sets the timeout time for subsequent DDE functions to specified value
       in milliseconds (1/1000 second).  Default is 3000 milliseconds (3
       seconds).  If the time elapses with no response, the WIL Interpreter
       will return an error.  The value set with DDETimeout stays in effect
       until changed by another DDETimeout statement or until the WIL program
       ends, whichever comes first.






       Example:
        DDETimeout(5000)
        Run("wincheck.exe", "TUT")
        channel = DDEInitiate("WinCheck", "TUT")
        If channel == 0 Then Goto failed
        output = DDERequest(channel, "GetChecking")
        DDETerminate(channel)
        WinClose("WinCheck")
        If output == "" Then Goto Failed
        Message("Account balance", output)
        Exit
        :failed
        Message("DDE operation unsuccessful", "Check your syntax")


       See Also:
          DDEExecute, DDEInitiate, DDEPoke, DDERequest, DDETerminate




       Debug
       Controls the debug mode.


       Syntax:
        Debug (mode)

       Parameters:
        (i) mode     @ON or @OFF

       Returns:
        (i)          previous debug mode

       Use this function to turn the debug mode on or off.  The default is
       @OFF.

       When debug mode is on, the WIL Interpreter will display the statement
       just executed, its result (if any), any error conditions, and the next
       statement to execute.

       The statements are displayed in a special dialog box which gives the
       user four options:  Next, Run, Cancel and Show Var.

       Next executes the next statement and remains in debug mode.

       Run exits debug mode and runs the rest of the program normally.

       Cancel terminates the current WIL program.

       Show Var displays the contents of a variable whose name the user
       entered in the edit box.






       Example:
        Debug(@ON)
        a = 6
        q = AskYesNo("Testing Debug Mode", "Is the Pope Catholic")
        Debug(@OFF)
        b = a + 4

       produces:














       ... then, if the user presses Next:














       ... and presses Next again:











       ... and then presses Yes:


















       etc.  (If the user had pressed No it would have said "VALUE=>0".)


       See Also:
          ErrorMode, LastError, SKDebug




       Delay
       Pauses execution for a specified amount of time.


       Syntax:
        Delay (seconds)

       Parameters:
        (i) seconds  integer seconds to delay (2 - 3600)

       Returns:
        (i)          always 1

       This function causes the currently-executing WIL program to be
       suspended for the specified period of time.  Seconds must be an
       integer between 2 and 3600.  Smaller or larger numbers will be
       adjusted accordingly.


       Example:
        Message("Wait", "About 15 seconds")
        Delay(15)
        Message("Hi", "I'm Baaaaaaack")


       See Also:
          Yield




       DialogBox
       Pops up a Windows dialog box defined by the WDG template file.






       Syntax:
        DialogBox (title, WDG-file)

       Parameters:
        (s) title    the title of the dialog box.
        (s) WDG-file the name of the WDG template file.

       Returns:
        (i)          always 0.

       Each element in the template file is enclosed in square brackets, and
       consists of a variable name, followed by one of the following symbols:

          Symbol Meaning           Example

            +    check box         [backup+1Save backup]
            #    edit box          [newfile#   ]
            \    file selection listbox        [editfile\     ]
            ^    radio button      [prog^1Note]     [prog^2Write]
            $    variable          [var$]

       The number following the check box and radio button symbols is the
       value which will get assigned to the variable if its corresponding box
       is checked, or button is selected.  Following the number is the
       descriptive text which will appear next to the box or button.

       When used in conjunction with a file selection list box variable with
       the same name, two of these symbols have special meanings:

            #    file mask edit box            [editfile#     ]
            $    directory variable            [editfile$     ]

       Anything not appearing within square brackets is displayed as text.

       See the separate manual section on Dialog Boxes (pg. 185) for more
       detailed information on using this function.


       Example:
        DialogBox("Edit a file", "edit.wdg")
        If backup == 0 Then Goto nobackup
        filebackupname = StrCat(FileRoot(editfile), ".", "bak")
        FileCopy(editfile, filebackupname, @TRUE)
        :nobackup
        If prog == 1 Then Run("notepad.exe", editfile)
        If prog == 2 Then Run("c:\win\apps\winedit.exe", editfile)

       Here is the template file, EDIT.WDG:





        [editfile$       ]
             File mask [editfile#    ]
        [editfile\                      ]
        [editfile\                      ]
        [editfile\                      ]
        [editfile\                      ]
        [editfile\                      ]
        [backup+1Save backup of file]
        [prog^1Notepad]     [prog^2WinEdit]


       See Also:
          AskLine, AskPassword, AskYesNo, ItemSelect




       DirChange
       Changes the current directory.  Can also log a new drive.


       Syntax:
        DirChange ([d:]path)

       Parameters:
        (s) [d:]     an optional disk drive to log onto.
        (s) path     the desired path.

       Returns:
        (i)          @TRUE if directory was changed;
                     @FALSE if the path could not be found.

       Use this function to change the current working directory to another
       directory, either on the same or a different disk drive.


       Example:
        DirChange("c:\")
        TextBox("This is your CONFIG.SYS file", "config.sys")


       See Also:
          DirGet, DirHome, LogDisk




       DirGet
       Gets the current working directory.


       Syntax:
        DirGet ( )

       Parameters:
        (none)






       Returns:
        (s)          current working directory.

       Use this function to determine which directory we are currently in.
       It's especially useful when changing drives or directories
       temporarily.


       Example:
        ; Get, then restore current working directory
        origdir = DirGet()
        DirChange("c:\")
        FileCopy("config.sys", "%origdir%xxxtemp.xyz", @FALSE)
        DirChange(origdir)


       See Also:
          CurrentFile, DirHome, DirWindows




       DirHome
       Returns directory containing the WIL Interpreter's executable files.


       Syntax:
        DirHome ( )

       Parameters:
        (none)

       Returns:
        (s)          pathname of the home directory.

       Use this function to determine the directory where the current WIL
       Interpreter's executable files are stored.


       Example:
        a = DirHome()
        Message("WIL Executable is in ", a)


       See Also:
          DirGet, DirWindows




       DirItemize
       Returns a space-delimited list of directories.


       Syntax:
        DirItemize (dir-list)






       Parameters:
        (s) dir-list a string containing a set of subdirectory names, which
                     may be wildcarded.

       Returns:
        (s)          list of directories.

       This function compiles a list of subdirectories and separates the
       names with spaces.

       This is especially useful in conjunction with the ItemSelect function,
       which enables the user to choose an item from such a space-delimited
       list.

       DirItemize("*.*") returns all subdirectories under the current
       directory.

       Note: Some shell or file manager applications using the WIL
       Interpreter allow an empty string ("") to be used as the "dir-list"
       parameter, in which case all subdirectories highlighted in the file
       display are returned.  However, if there are any directory names or
       wildcards in the string, all subdirectories matching the pathnames are
       returned, regardless of which ones are highlighted.


       Example:
        a = DirItemize("*.*")
        ItemSelect("Directories", a, " ")


       See Also:
          CurrentFile, FileItemize, ItemSelect, TextSelect, WinItemize




       DirMake
       Creates a new directory.


       Syntax:
        DirMake ([d:]path)

       Parameters:
        (s) [d:]     the desired disk drive.
        (s) path     the path to create.

       Returns:
        (i)          @TRUE if the directory was successfully created;
                     @FALSE if it wasn't.

       Use this function to create a new directory.


       Example:
        DirMake("c:\xxxstuff")







       See Also:
          DirRemove, DirRename




       DirRemove
       Removes a directory.


       Syntax:
        DirRemove (dir-list)

       Parameters:
        (s) dir-list a space-delimited list of directory pathnames.

       Returns:
        (i)          @TRUE if the directory was successfully removed;
                     @FALSE if it wasn't.

       Use this function to delete directories.  You can delete one or more
       at a time by separating directory names with spaces.  You cannot,
       however, use wildcards.


       Examples:
        DirRemove("c:\xxxstuff")

        DirRemove("tempdir1 tempdir2 tempdir3")


       See Also:
          DirMake, DirRename




       DirRename
       Renames a directory.


       Syntax:
        DirRename ([d:]oldpath, [d:]newpath)

       Parameters:
        (s) oldpath  existing directory name, with optional drive.
        (s) newpath  new name for directory.

       Returns:
        (i)          @TRUE if the directory was successfully renamed;
                     @FALSE if it wasn't.


       Example:
        DirRename("c:\temp", "c:\work")







       See Also:
          DirMake, DirRemove




       DirWindows
       Returns the name of the Windows or Windows System directory.


       Syntax:
        DirWindows (request#)

       Parameters:
        (i) request# see below.


       Returns:
        (s)          directory name.

       This function returns the name of either the Windows directory or the
       Windows System directory, depending on the request# specified.

          Req#   Return value

          0      Windows directory
          1      Windows System directory


       Example:
        DirChange(DirWindows(0))
        ini = ItemSelect("Select file to edit", FileItemize("*.ini"), " ")
        Run("notepad.exe", ini)


       See Also:
          DirGet, DirHome




       DiskFree
       Finds the total space available on a group of drives.


       Syntax:
        DiskFree (drive-list)

       Parameters:
        (s) drive-list     one or more drive letters, separated by spaces.

       Returns:
        (i)          the number of bytes available on all the specified
                     drives.





       This function takes a string consisting of drive letters, separated by
       spaces.  Only the first character of each non-blank group of
       characters is used to determine the drives, so you can use just the
       drive letters, or add a colon (:), or add a backslash (\), or even a
       whole pathname, and still get a perfectly valid result.


       Example:
        size = DiskFree("c d")
        Message("Space Available on C: and D:", size)


       See Also:
          DiskScan, FileSize




       DiskScan
       Returns list of drives.


       Syntax:
        DiskScan (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (s)          drive list.

       Scans disk drives on the system, and returns a space-delimited list of
       drives of the type specified by request#, in the form "A: B: C: D: ".

       The request# is a bitmask, so adding the values together (except for
       0) returns all drive types specified; eg., a request# of 3 returns
       floppy plus local hard drives.

          Req#   Return value

          0      List of unused disk IDs
          1      List of removable (floppy) drives
          2      List of local fixed (hard) drives
          4      List of remote (network) drives


       Example:
        hd = DiskScan(2)
        Message("Hard drives on system", hd)


       See Also:
          DiskFree, LogDisk








       Display
       Displays a message to the user for a specified period of time.


       Syntax:
        Display (seconds, title, text)

       Parameters:
        (i) seconds  seconds to display the message (1-3600).
        (s) title    title of the window to be displayed.
        (s) text     text of the window to be displayed.

       Returns:
        (i)          always 1.

       Use this function to display a message for a few seconds, and then
       continue processing without user input.

       Seconds must be an integer between 1 and 3600.  Smaller or larger
       numbers will be adjusted accordingly.

       The display box may be prematurely canceled by the user by clicking a
       mouse button, or hitting any key.


       Example:
        Display(3, "Current window is", WinGetActive())

       which produces something like this:







       See Also:
          Message, Pause




       DOSVersion
       Returns the version numbers of the current version of DOS.


       Syntax:
        DOSVersion (level)

       Parameters:
        (i) level    @MAJOR or @MINOR.

       Returns:
        (i)          integer or decimal part of DOS version number.






       @MAJOR returns the integer part (to the left of the decimal).
       @MINOR returns the decimal part (to the right of the decimal).

       If the version of DOS in use is 5.0, then:

          DOSVersion(@MAJOR)    ==   5
          DOSVersion(@MINOR)    ==   0


       Example:
        i = DOSVersion(@MAJOR)
        d = DOSVersion(@MINOR)
        If StrLen(d) == 1 Then d = StrCat("0", d)
        Message("DOS Version", "%i%.%d%")


       See Also:
          Environment, Version, WinVersion




       Drop
       Removes variables from memory.


       Syntax:
        Drop (var, [var...])

       Parameters:
        (i) var      variable names to remove.

       Returns:
        (i)          always 1.

       This function removes variables from the WIL Interpreter's variable
       list, and recovers the memory associated with the variable (and
       possibly related string storage).


       Example:
        a = "A variable"
        b = "Another one"
        Drop(a, b)       ; This removes A and B from memory


       See Also:
          IsDefined




       Else
       Continues a previous If statement.






       Syntax:
        Else statement

       Parameters:
        (s) statement any valid WIL function or command.

       This command continues the last-encountered If command.  It allows the
       user to specify an alternate action to be taken if the If condition
       was false.  If the previous If condition was false, the statement
       following the Else keyword is executed.  If the previous If condition
       was true, the statement following the Else keyword is ignored.


       Example:
        windir = DirWindows(0)
        inifiles = FileItemize("%windir%*.ini")
        ini = ItemSelect("INI file to edit", inifiles, " ")
        If ini == "" Then Exit
        Else Run("notepad.exe", ini)


       See Also:
          Goto, If ... Then, Then




       EndSession
       Ends the Windows session.


       Syntax:
        EndSession ( )

       Parameters:
        (none)

       Returns:
        (i)          always 0.

       Use this command to end the Windows session.


       Example:
        sure = AskYesNo ("End Session", "You SURE you want to exit
            Windows?")
        If sure == @No Then Goto cancel
        EndSession()
        :cancel
        Message("", "Exit Windows canceled")


       See Also:
          Exit, WinClose, WinCloseNot








       Environment
       Gets a DOS environment variable.


       Syntax:
        Environment (env-variable)

       Parameters:
        (s) env-variable   any defined environment variable.

       Returns:
        (s)          environment variable contents.

       Use this function to get the value of a DOS environment variable.

       Note: It is not possible to change a DOS environment variable.


       Example:
        ; Display the PATH for this DOS session
        currpath = Environment("PATH")
        Message("Current DOS Path", currpath)


       See Also:
          IniRead, Version, WinMetrics, WinParmGet




       ErrorMode
       Specifies how to handle errors.


       Syntax:
        ErrorMode (mode)

       Parameters:
        (i) mode     @CANCEL or @NOTIFY or @OFF.

       Returns:
        (i)          previous error setting.

       Use this function to control the effects of runtime errors.  The
       default is @CANCEL, meaning the execution of the WIL program will be
       canceled upon any error.

       @CANCEL:  All runtime errors will cause execution to be canceled.  The
       user will be notified which error occurred.

       @NOTIFY:  All runtime errors will be reported to the user, and the
       user can choose to continue if it isn't fatal.





       @OFF:  Minor runtime errors will be suppressed. Moderate and fatal
       errors will be reported to the user.  User has the option of
       continuing if the error is not fatal.

       In general, we suggest the normal state of the program should be
       ErrorMode(@CANCEL), especially if you are writing a WIL program for
       others to use.  You can always suppress errors you expect will occur
       and then re-enable ErrorMode (@CANCEL).


       Example:
        ; Delete xxxtest.xyz.  If file doesn't exist,
        ; continue execution; don't stop
        prevmode = ErrorMode(@OFF)
        FileDelete("c:\xxxtest.xyz")
        ErrorMode(prevmode)


       See Also:
          Debug, Execute, LastError




       Exclusive
       Controls whether or not other Windows programs will get any time to
       execute.


       Syntax:
        Exclusive (mode)

       Parameters:
        (i) mode     @ON or @OFF.

       Returns:
        (i)          previous Exclusive mode.

       Exclusive(@OFF) is the default mode.  In this mode,the WIL Interpreter
       is well-behaved toward other Windows applications.

       Exclusive(@ON) allows WIL programs to run somewhat faster, but causes
       the WIL Interpreter to be "greedier" about sharing processing time
       with other active Windows applications.  For the most part, this mode
       is useful only when you have a series of WIL statements which must be
       executed in quick succession.






       Example:
        Exclusive(@ON)
        x = 0
        start = DateTime()
        :add
        x = x + 1
        If x < 1000 Then Goto add
        stop = DateTime()
        crlf = StrCat(Num2Char(13), Num2Char(10))
        Message("Times", "Start: %start%%crlf%Stop:  %stop%")
        Exclusive(@OFF)


       See Also:
          Yield




       Execute
       Executes a statement in a protected environment.  Any errors
       encountered are recoverable.


       Syntax:
        Execute statement

       Parameters:
        (s) statement any executable WIL statement.

       Returns:
        (not applicable)

       Use this command to execute computed or user-entered statements.  Due
       to the built-in error recovery associated with Execute, it is ideal
       for interactive execution of user-entered commands.

       Note that the Execute command doesn't operate on a string, per se, but
       rather on a direct statement.  If you want to put a code segment into
       a string variable, you must use the substitution feature of the
       language, as in the example below.


       Example:
        cmd = ""
        cmd = AskLine("WIL Interactive", "Command:", cmd)
        Execute %cmd%


       See Also:
          ErrorMode








       Exit
       Unconditionally ends a WIL program.


       Syntax:
        Exit

       Parameters:
        (none)

       Returns:
        (not applicable)

       Use this command to immediately terminate a WIL program.  An Exit is
       implied at the end of each WIL program, and so is not necessary there.


       Example:
        a = 100
        Message("The value of a is", a)
        Exit


       See Also:
          Pause, Return, Terminate




       FileAppend
       Appends one or more files to another file.


       Syntax:
        FileAppend (source-list, destination)

       Parameters:
        (s) source-list    a string containing one or more filenames, which
                     may be wildcarded.
        (s) destination    target file name.

       Returns:
        (i)          @TRUE if all files were appended successfully;
                     @FALSE if at least one file wasn't appended.

       Use this function to append an individual file or a group of files to
       the end of an existing file.  If destination does not exist, it will
       be created.

       The file(s) specified in source-list will not be modified by this
       function.

       Source-list may contain * and ? wildcards.  Destination may not
       contain wildcards of any type; it must be a single file name.






       Examples:
        FileAppend("c:\config.sys", "c:\misc\config.sav")

        DirChange("c:\batch")
        FileDelete("allbats.fil")
        FileAppend("*.bat", "allbats.fil")


       See Also:
          FileCopy, FileDelete, FileExist




       FileAttrGet
       Returns file attributes.


       Syntax:
        FileAttrGet (filename)

       Parameters:
        (s) filename file whose attributes you want to determine.

       Returns:
        (s)          attribute settings.

       Returns attributes for the specified file, in a string of the form
       "RASH".  This string is composed of four individual attribute
       characters, as follows:

          Char   Symbol    Meaning

          1      R    Read-only ON
          2      A    Archive ON
          3      S    System ON
          4      H    Hidden ON

       A hyphen in any of these positions indicates that the specified
       attribute is OFF.  For example, the string "-A-H" indicates a file
       which has the Archive and Hidden attributes set.


       Example:
        editfile = "c:\config.sys"
        attr = FileAttrGet(editfile)
        If StrSub(attr, 1, 1) == "R" Then Goto readonly
        Run("notepad.exe", editfile)
        Exit
        :readonly
        Message("File is read-only", "Cannot edit %editfile%")


       See Also:
          FileAttrSet, FileTimeGet








       FileAttrSet
       Sets file attributes.


       Syntax:
        FileAttrSet (file-list, settings)

       Parameters:
        (s) file-list space-delimited list of files.
        (s) settings new attribute settings for those file(s).

       Returns:
        (i)          always 0.

       The attribute string consists of one or more of the following
       characters (an upper case letter turns the specified attribute ON, a
       lower case letter turns it OFF):

          R read only ON
          A archive ON
          S system ON
          H hidden ON

          r read only OFF
          a archive OFF
          s system OFF
          h hidden OFF


       Examples:
        FileAttrSet("win.ini system.ini", "rAsH")

        FileAttrSet("c:\command.com", "R")


       See Also:
          FileAttrGet, FileTimeTouch




       FileClose
       Closes a file.


       Syntax:
        FileClose (filehandle)

       Parameters:
        (i) filehandle     same integer that was returned by FileOpen.

       Returns:
        (i)          always 0.






       Example:
        ; the hard way to copy an ASCII file
        old = FileOpen("config.sys", "READ")
        new = FileOpen("sample.txt", "WRITE")
        :top
        x = FileRead(old)
        If x != "*EOF*" Then FileWrite(new, x)
        If x != "*EOF*" Then Goto top
        FileClose(new)
        FileClose(old)


       See Also:
          FileOpen, FileRead, FileWrite




       FileCopy
       Copies files.


       Syntax:
        FileCopy (source-list, destination, warning)

       Parameters:
        (s) source-list    a string containing one or more filenames, which
                     may be wildcarded.
        (s) destination    target file name.
        (i) warning  @TRUE if you want a warning before overwriting existing
                     files;
                     @FALSE if no warning desired.

       Returns:
        (i)          @TRUE if all files were copied successfully;
                     @FALSE if at least one file wasn't copied.

       Use this function to copy an individual file, a group of files using
       wildcards, or several groups of files by separating the names with
       spaces.

       You can also copy files to any COM or LPT device.

       Source-list may contain * and ? wildcards.  Destination may contain
       the * wildcard only.


       Examples:
        FileCopy("c:\config.sys", "d:", @FALSE)

        FileCopy("c:\*.sys", "d:devices\*.sys", @TRUE)

        FileCopy("c:\config.sys", "LPT1", @FALSE)






       See Also:
          FileDelete, FileExist, FileLocate, FileMove, FileRename




       FileDelete
       Deletes files.


       Syntax:
        FileDelete (file-list)

       Parameters:
        (s) file-list a string containing one or more filenames, which may be
                     wildcarded.

       Returns:
        (i)          @TRUE if all the files were deleted;
                     @FALSE if a file didn't exist or is marked with the
                     READ-ONLY attribute.

       Use this function to delete an individual file, a group of files using
       wildcards, or several groups of files by separating the names with
       spaces.


       Example:
        FileDelete("*.bak temp???.fil")


       See Also:
          FileExist, FileLocate, FileMove, FileRename




       FileExist
       Tests for the existence of files.


       Syntax:
        FileExist (filename)

       Parameters:
        (s) filename either a fully qualified filename with drive and path,
                     or just a filename and extension.

       Returns:
        (i)          @TRUE if the file exists;
                     @FALSE if it doesn't exist or if the pathname is
                     invalid.

       This function is used to test whether or not a specified file exists.





       If a fully-qualified file name is used, only the specified drive and
       directory will be checked for the desired file.  If only the root and
       extension are specified, then first the current directory is checked
       for the file, and then, if the file is not found in the current
       directory, all directories in the DOS path are searched.


       Examples:
        ; check for file in current directory
        fex = FileExist(StrCat(DirGet(), "myfile.txt"))
        tex = StrSub("NOT", 1, StrLen("NOT") * fex)
        Message("MyFile.Txt"," Is %tex%in the current directory")

        ; check for file someplace along path
        fex = FileExist("myfile.txt")
        tex = StrSub("NOT", 1, StrLen("NOT") * fex)
        Message("MyFile.Txt", " Is %tex% in the DOS path")


       See Also:
          FileLocate




       FileExtension
       Returns extension of file.


       Syntax:
        FileExtension (filename)

       Parameters:
        (s) filename [optional path]full file name, including extension.

       Returns:
        (s)          file extension.

       This function parses the passed filename and returns the extension
       part of the filename.

       Example:
        ; prevent the user from editing a COM or EXE file
        allfiles = FileItemize("*.*")
        editfile = ItemSelect("Select file to edit", allfiles, " ")
        ext = FileExtension(editfile)
        If (ext == "com") || (ext == "exe") Then Goto noedit
        run("notepad.exe", editfile)
        exit
        :noedit
        Message ("Sorry", "You may not edit a program file")


       See Also:
          DialogBox, FilePath, FileRoot








       FileItemize
       Returns a space-delimited list of files.


       Syntax:
        FileItemize (file-list)

       Parameters:
        (s) file-list a string containing a list of filenames, which may be
                     wildcarded.

       Returns:
        (s)          space-delimited list of files.

       This function compiles a list of filenames and separates the names
       with spaces.

       This is especially useful in conjunction with the ItemSelect function,
       which lets the user choose an item from such a space-delimited list.

       Note: Some shell or file manager applications using the WIL
       Interpreter allow an empty string ("") to be used as the "file-list"
       parameter, in which case all files highlighted in the file display are
       returned.  However, if there are any file names or wildcards in the
       string, all files matching the file names are returned, regardless of
       which ones are highlighted.


       Examples:
        FileItemize("*.bak")         ;all BAK files

        FileItemize("*.arc *.zip *.lzh")  ;compressed files

        ; Get which .INI file to edit
        ifiles = FileItemize("c:\windows\*.ini")
        ifile = ItemSelect(".INI Files", ifiles, " ")
        RunZoom("notepad", ifile)
        Drop(ifiles, ifile)


       See Also:
          CurrentFile, DirItemize, ItemSelect, TextSelect, WinItemize




       FileLocate
       Finds file in current directory or along the DOS path.


       Syntax:
        FileLocate (filename)






       Parameters:
        (s) filename full file name, including extension.

       Returns:
        (s)          fully-qualified path name.

       This function is used to obtain the fully qualified path name of a
       file.  The current directory is checked first, and if the file is not
       found, the DOS path is searched.  The first occurrence of the file is
       returned.


       Example:
        ; Edit WIN.INI
        winini = FileLocate("win.ini")
        If winini == "" Then Goto notfound
        Run("notepad.exe", winini)
        Exit
        :notfound
        Message("???", "WIN.INI not found")


       See Also:
          FileExist




       FileMove
       Moves files.


       Syntax:
        FileMove (source-list, destination, warning)

       Parameters:
        (s) source-list    one or more filenames separated by spaces.
        (s) destination    target filename.
        (i) warning  @TRUE if you want a warning before overwriting existing
                     files;
                     @FALSE if no warning desired.

       Returns:
        (i)          @TRUE if the file was moved;
                     @FALSE if the source file was not found or had the READ-
                     ONLY attribute, or the target filename is invalid.

       Use this function to move an individual file, a group of files using
       wildcards, or several groups of files by separating the names with
       spaces.

       You can also move files to another drive, or to any COM or LPT device.

       Source-list may contain * and ? wildcards.  Destination may contain
       the * wildcard only.






       Examples:
        FileMove("c:\config.sys", "d:", @FALSE)

        FileMove("c:\*.sys", "d:*.sys", @TRUE)


       See Also:
          FileCopy, FileDelete, FileExist, FileLocate, FileRename




       FileOpen
       Opens a STANDARD ASCII (only) file for reading or writing.


       Syntax:
        FileOpen (filename, open-type)

       Parameters:
        (s) filename name of the file to open.
        (s) open-type "READ" or "WRITE".

       Returns:
        (i)          filehandle

       The filehandle returned by the FileOpen function may be subsequently
       used by the FileRead, FileWrite, and FileClose functions.


       Examples:
        ; To open for reading:
        handle = FileOpen("stuff.txt", "READ")

        ; To open for writing:
        handle = FileOpen("stuff.txt", "WRITE")


       See Also:
          FileClose, FileRead, FileWrite




       FilePath
       Returns path of file.


       Syntax:
        FilePath (filename)

       Parameters:
        (s) filename fully qualified file name, including path.

       Returns:
        (s)          fully qualified path name.







       FilePath parses the passed filename and returns the drive and path of
       the file specification, if any.

       Example:
        coms = Environment("COMSPEC")
        compath = FilePath(coms)
        Message("", "Your command processor is located in %compath%")


       See Also:
          FileExtension, FileRoot




       FileRead
       Reads data from a file.


       Syntax:
        FileRead (filehandle)

       Parameters:
        (i) filehandle     same integer that was returned by FileOpen.

       Returns:
        (s)          line of data read from file.


       When the end of the file is reached, the string *EOF* will be
       returned.


       Example:
        handle = FileOpen("autoexec.bat", "READ")
        :top
        line = FileRead(handle)
        Display(4, "AUTOEXEC DATA", line)
        If line != "*EOF*" Then Goto top
        FileClose(handle)


       See Also:
          FileClose, FileOpen, FileWrite




       FileRename
       Renames files.


       Syntax:
        FileRename (source-list, destination)






       Parameters:
        (s) source-list    one or more filenames, separated by spaces.
        (s) destination    target filename.

       Returns:
        (i)          @TRUE if the file was renamed;
                     @FALSE if the source file was not found or had the READ-
                     ONLY attribute, or the target filename is invalid.

       Use this function to rename an individual file, a group of files using
       wildcards, or several groups of files by separating the names with
       spaces.

       Note: Unlike FileMove, you cannot make a file change its resident disk
       drive with FileRename.

       Source-list may contain * and ? wildcards.  Destination may contain
       the * wildcard only.


       Examples:
        FileRename("c:\config.sys", "config.old")

        FileRename("c:\*.txt", "*.bak")


       See Also:
          FileCopy, FileExist, FileLocate, FileMove




       FileRoot
       Returns root of file.


       Syntax:
        FileRoot (filename)

       Parameters:
        (s) filename [optional path]full file name, including extension.

       Returns:
        (s)          file root.


       FileRoot parses the passed filename and returns the root part of the
       filename.






       Example:
        allfiles = FileItemize("*.*")
        editfile = ItemSelect("Select file to edit", allfiles, " ")
        root = FileRoot(editfile)
        ext = FileExtension(editfile)
        lowerext = StrLower(ext)
        nicefile = StrCat(root, ".", lowerext)
        Message("", "You are about to edit %nicefile%.")
        Run("notepad.exe", editfile)


       See Also:
          FileExtension, FilePath




       FileSize
       Finds the total size of a group of files.


       Syntax:
        FileSize (file-list)

       Parameters:
        (s) file-list zero or more filenames, separated by spaces.

       Returns:
        (i)          total bytes taken up by the specified file(s).

       This function returns the total size of the specified files.  Note
       that it doesn't handle wildcarded filenames.  You can, however, use
       FileItemize on a wildcarded filename and use the resulting string as a
       FileSize parameter.


       Example:
        size = FileSize(FileItemize("*.*"))
        Message("Size of All Files in Directory", size)


       See Also:
          DiskFree




       FileTimeGet
       Returns file date and time.


       Syntax:
        FileTimeGet (filename)

       Parameters:
        (s) filename name of file for which you want the date and time.






       Returns:
        (s)          file date and time.

       This function will return the date and time of a file, in a pre-
       formatted string.  The format it is returned in depends on the date
       format specified in the [Intl] section of the WIN.INI file:

       mm/dd/yy  hh:mmXX
       dd/mm/yy  hh:mmXX
       yy/mm/dd  hh:mmXX

       Where:
          mm  is the month (e.g. 10)
          dd  is the day of the month (e.g. 23)
          yy  is the year (e.g. 90)
          hh  is the hours
          mm  is the minutes
          XX  is the Day/Night code (e.g. AM or PM)

       There are two spaces between the date and the time.

       The WIN.INI file will be examined to determine which format to use.
       You can adjust the WIN.INI file via the International section of
       Control Panel if the format isn't what you prefer.


       Example:
        oldtime = FileTimeGet("win.ini")
        Run("notepad.exe", "win.ini")
        WinWaitClose("Notepad - WIN.INI")
        newtime = FileTimeGet("win.ini")
        If StrCmp(oldtime, newtime) == 0 Then Exit
        Message("", "WIN.INI has been changed")


       See Also:
          DateTime, FileAttrGet, FileTimeTouch




       FileTimeTouch
       Sets file(s) to current time.


       Syntax:
        FileTimeTouch (file-list)

       Parameters:
        (s) file-list a space-delimited list of files

       Returns:
        (i)          always 0





       File-list is a space-delimited list of files, which may not contain
       wildcards.  The path is searched if the file is not found in current
       directory and if the directory is not specified in file-list.


       Example:
        FileTimeTouch("wac.c wac.rc")
        Run("make.exe", "-fwac.mak")


       See Also:
          FileAttrSet, FileTimeGet




       FileWrite
       Writes data to a file.


       Syntax:
        FileWrite (filehandle, output-data)

       Parameters:
        (i) filehandle     same integer that was returned by FileOpen.
        (s) output-data    data to write to file.

       Returns:
        (i)          always 0.



       Example:
        handle = FileOpen("stuff.txt", "WRITE")
        FileWrite(handle, "Gobbledygook")
        FileClose(handle)


       See Also:
          FileClose, FileOpen, FileRead




       Goto
       Changes the flow of control in a WIL program.


       Syntax:
        Goto label

       Parameters:
        (s) label    user-defined identifier.

       Goto label causes an unconditional branch to the line in the program
       marked :label, where the identifier is preceded by a colon (:).






       Example:
        If WinExist("Solitaire") == @FALSE Then Goto open
        WinActivate("Solitaire")
        Goto loaded
        :open
        Run("sol.exe", "")
        :loaded


       See Also:
          Else, If ... Then, Then




       IconArrange
       Rearranges icons.


       Syntax:
        IconArrange ( )

       Parameters:
        (none)

       Returns:
        (i)          always 0.

       This function rearranges the icons at the bottom of the screen,
       spacing them evenly.  It does not change the order in which the icons
       appear.


       Example:
        IconArrange ( )


       See Also:
          RunIcon, WinArrange, WinIconize, WinPlaceSet




       If...Then
       Conditionally performs a function.


       Syntax:
        If condition Then statement

       Parameters:
        (s) condition an expression to be evaluated.
        (s) statement any valid WIL function or command.

       If the condition following the If keyword is true, the statement
       following the Then keyword is executed.  If the condition following





       the If keyword is false, the statement following the Then keyword is
       ignored.

       See the Else and Then commands for additional flexibility in
       conditional processing.


       Example:
        sure = AskYesNo("End Session", "Really quit Windows?")
        If sure == @YES Then EndSession()


       See Also:
          Else, Goto, Then




       IgnoreInput
       Turns off hardware input to windows.


       Syntax:
        IgnoreInput (mode)

       Parameters:
        (i) mode     @TRUE or @FALSE.

       Returns:
        (i)          previous IgnoreInput mode.


       IgnoreInput causes mouse movements, clicks and keyboard entry to be
       completely ignored.  Good for self-running demos.

       Warning: If you are not careful with the use of IgnoreInput, you can
       lock up your computer!


       Example:
        username = AskLine("Hello", "Please enter your name","")
        IgnoreInput(@TRUE)
        Call("demo.wbt", username)
        IgnoreInput(@FALSE)


       See Also:
          WaitForKey




       IniDelete
       Removes a line or section from WIN.INI.






       Syntax:
        IniDelete (section, keyname)

       Parameters:
        (s) section  the major heading under which the item is located.
        (s) keyname  the name of the item to delete.

       Returns:
        (i)          always 0

       This function will remove the specified line from the specified
       section in WIN.INI.  You can remove an entire section, instead of just
       a single line, by specifying a keyword of @WHOLESECTION.  Case is not
       significant in section or keyname.


       Examples:
        IniDelete("Desktop", "Wallpaper")

        IniDelete("Quicken",@WHOLESECTION)


       See Also:
          IniDeletePvt, IniItemize, IniRead, IniWrite




       IniDeletePvt
       Removes a line or section from a private INI file.


       Syntax:
        IniDeletePvt (section, keyname, filename)

       Parameters:
        (s) section  the major heading under which the item is located.
        (s) keyname  the name of the item to delete.
        (s) filename name of the INI file.

       Returns:
        (i)          always 0.

       This function will remove the specified line from the specified
       section in a private INI file.  You can remove an entire section,
       instead of just a single line, by specifying a keyword of
       @WHOLESECTION.  Case is not significant in section or keyname.


       Example:
        IniDeletePvt("Current Users", "Excel", "meter.ini")


       See Also:
          IniDelete, IniItemizePvt, IniReadPvt, IniWritePvt








       IniItemize
       Lists keywords or sections in WIN.INI.


       Syntax:
        IniItemize (section)

       Parameters:
        (s) section  the major heading to itemize.

       Returns:
        (s)          list of keywords or sections.

       IniItemize will scan the specified section in WIN.INI, and return a
       tab-delimited list of all keyword names contained within that section.
       If a null string ("") is given as the section name, IniItemize will
       return a list of all section names contained within WIN.INI.  Returns
       "(None)" if the specified section does not exist; returns a null
       string ("") if the section exists but is empty.  Case is not
       significant in section names.


       Examples:
        ; Returns all keywords in the [Extensions] section
        keywords = IniItemize("Extensions")

        ; Returns all sections in the entire WIN.INI file
        sections = IniItemize("")


       See Also:
          IniDelete, IniItemizePvt, IniRead, IniWrite




       IniItemizePvt
       Lists keywords or sections in a private INI file.


       Syntax:
        IniItemizePvt (section, filename)

       Parameters:
        (s) section  the major heading to itemize.
        (s) filename name of the INI file.

       Returns:
        (s)          list of keywords or sections.

       IniItemizePvt will scan the specified section in a private INI file,
       and return a tab-delimited list of all keyword names contained within
       that section.  If a null string ("") is given as the section name,
       IniItemizePvt will return a list of all section names contained within





       the file.  Returns "(None)" if the specified section does not exist;
       returns a null string ("") if the section exists but is empty.  Case
       is not significant in section names.


       Example:
        ; Returns all keywords in the [Boot] section of SYSTEM.INI
        keywords = IniItemizePvt("Boot", "system.ini")


       See Also:
          IniDeletePvt, IniItemize, IniReadPvt, IniWritePvt




       IniRead
       Reads data from the WIN.INI file.


       Syntax:
        IniRead (section, keyname, default)

       Parameters:
        (s) section  the major heading to read the data from.
        (s) keyname  the name of the item to read.
        (s) default  string to return if the desired item is not found.

       Returns:
        (s)          data from WIN.INI file.

       This function allows a program to read data from the WIN.INI file.

       The WIN.INI file has the form:

          [section]
          keyname=settings


       Most of the entries in WIN.INI are set from the Windows Control Panel
       program, but individual applications can also use it to store option
       settings in their own sections.


       Example:
        ; Find the default output device
        a = IniRead("windows", "device", "No Default")
        Message("Default Output Device", a)


       See Also:
          Environment, IniDelete, IniItemize, IniReadPvt, IniWrite








       IniReadPvt
       Reads data from a private INI file.


       Syntax:
        IniReadPvt (section, keyname, default, filename)

       Parameters:
        (s) section  the major heading to read the data from.
        (s) keyname  the name of the item to read.
        (s) default  string to return if the desired item is not found.
        (s) filename name of the INI file.

       Returns:
        (s)          data from the INI file.

       Looks up a value in the "filename".INI file.  If the value is not
       found, the "default" will be returned.


       Example:
        IniReadPvt("Main", "Lang", "English", "WB.INI")

       Given the following segment from WB.INI:

          [Main]
          Lang=French

       The statement above would return:

          French


       See Also:
          Environment, IniDeletePvt, IniItemizePvt, IniRead, IniWritePvt




       IniWrite
       Writes data to the WIN.INI file.


       Syntax:
        IniWrite (section, keyname, data)

       Parameters:
        (s) section  major heading to write the data to.
        (s) keyname  name of the data item to write.
        (s) data     string to write to the WIN.INI file.

       Returns:
        (i)          always 1.





       This command allows a program to write data to the WIN.INI file.  The
       "section" is added to the file if it doesn't already exist.


       Example:
        ; Change the list of pgms to load upon Windows
        ; startup
        loadprogs = IniRead("windows", "load", "")
        newprogs = AskLine("Add Pgm To LOAD= Line", "Add:", loadprogs)
        IniWrite("windows", "load", newprogs)


       See Also:
          IniDelete, IniItemize, IniRead, IniWritePvt




       IniWritePvt
       Writes data to a private INI file.


       Syntax:
        IniWritePvt (section, keyname, data, filename)

       Parameters:
        (s) section  major heading to write the data to.
        (s) keyname  name of the data item to write.
        (s) data     string to write to the INI file.
        (s) filename name of the INI file.

       Returns:
        (i)          always 1.

       Writes a value in the "filename".INI file.


       Example:
        IniWritePvt("Main", "Lang", "French, "WB.INI")

       This would create the following entry in WB.INI:

          [Main]
          Lang=French


       See Also:
          IniDeletePvt, IniItemizePvt, IniReadPvt, IniWrite




       IntControl
       Internal control functions.






       Syntax:
        IntControl (request#, p1, p2, p3, p4)

       Parameters:
        (i) request# specifies which sub-function is to be performed (see
                     below).
        (s) p1 - p4  parameters which may be required by the function (see
                     below).

       Returns:
        (s)          varies (see below).

       Short for Internal Control, a special function that permits numerous
       internal operations in the various products.  The first parameter of
       IntControl defines exactly what the function does, the other
       parameters are possible arguments to the function.

       Refer to your product documentation for any further information on
       this function.

       Warning: Many of these operations are useful only under special
       circumstances, and/or by technically knowledgeable users.  Some could
       lead to adverse side effects.  If it isn't clear to you what a
       particular function does, don't use it.


       IntControl (1, p1, 0, 0, 0)
       Just a test IntControl.  It echoes back P1 & P2 and P3 & P4 in a pair
       of message boxes.


       IntControl (4, p1, 0, 0, 0)
       Controls whether or not a dialog box with a file listbox in it has to
       return a file name, or may return merely a directory name or nothing.

          P1   Meaning

          0    May return nothing, or just a directory name
          1    Must return a file name (default)


       IntControl (5, p1, 0, 0, 0)
       Controls whether system & hidden files are seen and processed.

          P1   Meaning

          0    System & Hidden files not used (default)
          1    System & Hidden files seen and used


       IntControl (10, p1, 0, 0, 0)
       Interrogates the Command Extender DLL status

          P1   Meaning





          0    Command Extender present
               0     No
               1     Yes

          1    Command Extender version
               -1    No Extender present
               0     Incompatible extender present
               (other)Extender version code

          2    Interpreter's Extender interface code

          3    Name of Extender DLL


       IntControl (20, 0, 0, 0, 0)
       Returns window handle of current parent window.


       IntControl (21, p1, 0, 0, 0)
       Returns window handle of window matching the partial window-name in
       p1.


       IntControl (22, p1, p2, p3, p4)
       Issues a Windows "SendMessage".

          p1   Window handle to send to
          p2   Message ID number (in decimal)
          p3   wParam value
          p4   assumed to be a character string.  String is copied to a
               GMEM_LOWER buffer, and a LPSTR to the copied string is passed
               as lParam. The GMEM_LOWER buffer is freed immediately upon
               return from the SendMessage


       IntControl (23, 0, 0, 0, 0)
       Issues a windows PostMessage

          p1   Window handle
          p2   Message ID number (in decimal)
          p3   wParam
          p4   lParam -- assumed to be numeric


       IntControl (66, 0, 0, 0, 0)
       Restarts Windows, just like exiting to DOS and typing WIN again.
       Could be used to restart Windows after editing the SYSTEM.INI file to
       change video modes.


       IntControl (67, 0, 0, 0, 0)
       Performs a warm boot of the system, just like <Ctrl-Alt-Del>.  Could
       be used to reboot the system after editing the AUTOEXEC.BAT or
       CONFIG.SYS files.

       Note: IntControl(67) requires Windows 3.1 or higher.  Under Windows
       3.0, it behaves just like IntControl(66) and restarts Windows.








       IsDefined
       Determines if a variable name is currently defined.


       Syntax:
        IsDefined (var)

       Parameters:
        (s) var      a variable name.

       Returns:
        (i)          @YES if the variable is currently defined;
                     @NO if it was never defined or has been dropped.

       A variable is defined the first time it appears to the left of an
       equal sign in a statement.  It stays defined until it is explicitly
       dropped with the Drop function, or until the current invocation of the
       WIL Interpreter gets closed.


       Example:
        def = IsDefined(thisvar)
        If def == @FALSE Then Message("ERROR!", "Variable not defined")


       See Also:
          Drop




       IsKeyDown
       Tells about keys/mouse.

       Syntax:
        IsKeyDown(keycodes)

       Parameters:
        (i) keycodes @SHIFT and/or @CTRL.

       Returns:
        (i)          @YES if the key is down;
                     @NO if the key is not down.


       Determines if the Shift key or the Ctrl key is currently down.

       Note: The right mouse button is the same as Shift, and the middle
       mouse button is the same as Ctrl.






       Examples:
        IsKeyDown(@SHIFT)

        IsKeyDown(@CTRL)

        IsKeyDown(@CTRL | @SHIFT)

        IsKeyDown(@CTRL & @SHIFT)


       See Also:
          WaitForKey




       IsLicensed
       Tells if the calling application is licensed.


       Syntax:
        IsLicensed ( )

       Parameters:
        (none)

       Returns:
        (i)          @YES if it is licensed;
                     @NO if it is not licensed.


       Returns information on whether or not the currently-running version of
       the calling application is a licensed copy.


       Example:
        IsLicensed()


       See Also:
          Version




       IsMenuChecked [*M]
       Determines if a menu item has a checkmark next to it.


       Syntax:
        IsMenuChecked (menuname)

       Parameters:
        (s) menuname name of the menu item to test.






       Returns:
        (i)          @YES if the menu item has a checkmark;
                     @NO if it doesn't.

       You can place a checkmark next to a menu item with the MenuChange
       command, to indicate an option has been enabled.  This function lets
       you determine if the menu item has already been checked or not.

       Note: This command is not part of the WIL Interpreter package, but is
       documented here because it has been implemented in many of the shell
       or file manager-type applications which use the WIL Interpreter.


       Example:
        ; assume we've defined a "Misc | Prompt Often" menu item
        prompt = IsMenuChecked("MiscPromptOften")
        ifprompt = SubStr(";", 1, (prompt == @FALSE))
        Execute %ifprompt% confirm = AskYesNo("???", "REALLY do this?")
        ; some risky operation the user has just confirmed they want to do
        Execute %ifprompt% Terminate(confirm != @YES, "", "")


       See Also:
          IsMenuEnabled, MenuChange




       IsMenuEnabled [*M]
       Determines if a menu item has been enabled.


       Syntax:
        IsMenuEnabled (menuname)

       Parameters:
        (s) menuname name of the menu item to test.

       Returns:
        (i)          @YES if the menu item is enabled;
                     @NO if it is disabled & grayed.

       You can disable a menu item with the MenuChange command if you want to
       prevent the user from choosing it.  It shows up on the screen as a
       grayed item.  IsMenuEnabled lets you determine if the menu item is
       currently enabled or not.

       Note: This command is not part of the WIL Interpreter package, but is
       documented here because it has been implemented in many of the shell
       or file manager-type applications which use the WIL Interpreter.


       Example:
        ; allow editing of autoexec.bat file only if choice enabled
        Terminate(!IsMenuEnabled("UtilitiesEditBatFile"), "", "")
        Run("notepad.exe", "c:\autoexec.bat")







       See Also:
          IsMenuChecked, MenuChange




       IsNumber
       Determines whether a variable contains a valid number.


       Syntax:
        IsNumber (string)

       Parameters:
        (s) string   string to test to see if it represents a valid number.

       Returns:
        (i)          @YES if it contains a valid number;
                     @NO if it doesn't.

       This function determines if a string variable contains a valid
       integer.  Useful for checking user input prior to using it in
       computations.


       Example:
        a = AskLine("ISNUMBER", "Enter a number", "0")
        If IsNumber(a) == @NO Then Message("", "You didn't enter a
            number")


       See Also:
          Abs, Char2Num, Num2Char




       ItemCount
       Returns the number of items in a list.


       Syntax:
        ItemCount (list, delimiter)

       Parameters:
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (i)          the number of items in the list.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,





       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        a = FileItemize("*.*")
        n = ItemCount(a, " ")
        Message("Note", "There are %n% files")


       See Also:
          ItemExtract, ItemSelect




       ItemExtract
       Returns the selected item from a list.


       Syntax:
        ItemExtract (index, list, delimiter)

       Parameters:
        (i) index    the position in list of the item to be selected.
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (s)          the selected item.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        bmpfiles = FileItemize("*.bmp")
        bmpcount = ItemCount(bmpfiles, " ")
        pos = (Random(bmpcount - 1)) + 1
        paper = ItemExtract(pos, bmpfiles, " ")
        Wallpaper(paper, @FALSE)


       See Also:
          ItemCount, ItemLocate, ItemSelect, ItemSort




       ItemInsert
       Adds an item to a list.






       Syntax:
        ItemInsert (item, index, list, delimiter)

       Parameters:
        (s) item     a new item to add to list.
        (i) index    the position in list after which the item will be
                     inserted.
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (s)          new list, with item inserted.

       This function inserts a new item into an existing list, at the
       position following index.  It returns a new list, with the specified
       item inserted; the original list (list) is unchanged.  For example,
       specifying an index of 1 causes the new item to be inserted after the
       first item in the list; i.e., the new item becomes the second item in
       the list.

       You can specify an index of 0 to add the item to the beginning of the
       list, and an index of -1 to append the item to the end of the list.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        newlist = ItemInsert(item, index, list, delimiter)


       See Also:
          ItemCount, ItemRemove




       ItemLocate
       Returns the position of an item in a list.


       Syntax:
        ItemLocate (item, list, delimiter)

       Parameters:
        (s) item     item to search for in list.
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (i)          position in list of item, or 0 if no match found.





       This function finds the first occurrence of item in the specified
       list, and returns the position of the item (the first item in a list
       has a position of 1).  If the item is not found, the function will
       return a 0.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        ItemLocate(item, list, delimiter)


       See Also:
          ItemExtract




       ItemRemove
       Removes an item from a list.


       Syntax:
        ItemRemove (index, list, delimiter)

       Parameters:
        (i) index    the position in list of the item to be removed.
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (s)          new list, with item removed.

       This function removes the item at the position specified by index from
       a list.  The delimiter following the item is removed as well.  It
       returns a new list, with the specified item removed; the original list
       (list) is unchanged.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        newlist = ItemRemove(index, list, delimiter)


       See Also:
          ItemCount, ItemInsert








       ItemSelect
       Allows the user to choose an item from a listbox.


       Syntax:
        ItemSelect (title, list, delimiter)

       Parameters:
        (s) title    the title of the dialog box to display.
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (s)          the selected item.

       This function displays a dialog box with a listbox inside.  This
       listbox is filled with a sorted list of items taken from a string you
       provide to the function.

       Each item in the string must be separated ("delimited") by a
       character, which you also pass to the function.

       The user selects one of the items by either doubleclicking on it, or
       single-clicking and pressing OK.  The item is returned as a string.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        DirChange("c:\winword")
        alldotfiles = FileItemize("*.dot")
        dotfile = ItemSelect("W4W Templates", alldotfiles, " ")
        Run("winword.exe", dotfile)

       Which would produce:






















       See Also:
          AskYesNo, DialogBox, DirItemize, Display, FileItemize, ItemCount,
          ItemExtract, Message, Pause, TextBox, TextSelect, WinItemize




       ItemSort
       Sorts a list.


       Syntax:
        ItemSort (list, delimiter)

       Parameters:
        (s) list     a string containing a list of items.
        (s) delimiter a character to act as a delimiter between items in the
                     list.

       Returns:
        (s)          new, sorted list.

       This function sorts a list, using an ANSI sort sequence.  It returns a
       new, sorted list; the original list is unchanged.

       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.


       Example:
        newlist = ItemSort(list, delimiter)


       See Also:
          ItemExtract








       LastError
       Returns the most-recent error encountered during the current WIL
       program.


       Syntax:
        LastError ( )

       Parameters:
        (none)

       Returns:
        (i)          most-recent WIL error code encountered.

       WIL errors are numbered according to their severity.  "Minor" errors
       go from 1000 through 1999.  Moderate errors are 2000 through 2999.
       Fatal errors are numbered 3000 to 3999.

       Depending on which error mode is active when an error occurs, you may
       not get a chance to check the error code.  See ErrorMode for a
       discussion of default error handling.

       Don't bother checking for "fatal" error codes.  When a fatal error
       occurs, the WIL program is canceled before the next WIL statement gets
       to execute (regardless of which error mode is active).

       Every time the LastError function is called, the "last error"
       indicator is reset to zero.

       A full listing of possible errors you can encounter in processing a
       WIL program is in Appendix B (pg. 191).


       Example:
        ErrorMode(@OFF)
        FileCopy("data.dat", "c:\backups", @FALSE)
        ErrorMode(@CANCEL)
        If LastError() == 1006 Then Message("Error", "Please call  Tech
        Support at 555-9999.")


       See Also:
          Debug, ErrorMode




       LogDisk
       Logs (activates) a disk drive.


       Syntax:
        LogDisk (drive-letter)






       Parameters:
        (s) drive-letter   the disk drive to log into.

       Returns:
        (i)          @TRUE if the current drive was changed;
                     @FALSE if the drive doesn't exist.

       Use this function to change to a different disk drive.


       Example:
        LogDisk("c:")


       See Also:
          DirChange, DiskScan




       Max
       Returns largest number in a list of numbers.


       Syntax:
        Max (integer [, integer...])

       Parameters:
        (i) integer  an integer number.

       Returns:
        (i)          largest parameter.

       Use this function to determine the largest of a set of comma-delimited
       integers.


       Example:
        a = Max(5, -37, 125, 34, 2345, -32767)
        Message("Largest number is", a)


       See Also:
          Abs, Average, Min, Random




       MenuChange [*M]
       Checks, unchecks, enables, or disables a menu item.


       Syntax:
        MenuChange (menuname, flags)






       Parameters:
        (s) menuname menu item whose status you wish to change.
        (s) flags    @CHECK, @UNCHECK, @ENABLE, or @DISABLE.

       Returns:
        (i)          always 1.

       There are currently two ways you can modify a menu item:

       You can check and uncheck the item to imply that it corresponds to an
       option that can be turned on or off.

       You can temporarily disable the item (it shows up as gray) and later
       re-enable it.

       The two sets of flags (@Check/@UnCheck and @Enable/@Disable) can be
       combined in one function call by using the | (or) operator.

       Note: This command is not part of the WIL Interpreter package, but is
       documented here because it has been implemented in many of the shell
       or file manager-type applications which use the WIL Interpreter.


       Example:
        MenuChange("FilePrint", @Disable)
        MenuChange("WPWrite", @Enable | @Check)


       See Also:
          IsMenuChecked, IsMenuEnabled




       Message
       Displays a message to the user.


       Syntax:
        Message (title, text)

       Parameters:
        (s) title    title of the message box.
        (s) text     text to display in the message box.

       Returns:
        (i)          always 1.

       Use this function to display a message to the user.  The user must
       respond by selecting the OK button before processing will continue.


       Example:
        Message("Current directory is", DirGet())

       which produces:













       See Also:
          Display, Pause




       Min
       Returns lowest number in a list of numbers.


       Syntax:
        Min (integer [, integer...])

       Parameters:
        (i) integer  an integer number.

       Returns:
        (i)          lowest parameter.

       Use this function to determine the lowest of a set of comma-delimited
       integers.


       Example:
        a = Min( 5, -37, 125, 34, 2345, -32767)
        Message("Smallest number is", a)


       See Also:
          Abs, Average, Max, Random




       MouseInfo
       Returns assorted mouse information.


       Syntax:
        MouseInfo (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (s)          see below.

       The information returned by MouseInfo depends on the value of
       request#.





          Req# Return value

          0    Window name under mouse
          1    Top level parent window name under mouse
          2    Mouse coordinates, assuming a 1000x1000 virtual screen
          3    Mouse coordinates in absolute numbers
          4    Status of mouse buttons, as a bitmask:

                 BinaryDecimal  Meaning

                 000   0      No buttons down
                 001   1      Right button down
                 010   2      Middle button down
                 011   3      Right and Middle buttons down
                 100   4      Left button down
                 101   5      Left and Right buttons down
                 110   6      Left and Middle buttons down
                 111   7      Left, Middle, and Right buttons down

       For example, if mouse is at the center of a 640x480 screen and above
       the "Clock" window, and the left button is down, the following values
       would be returned:

          Req# Return value

          1    "Clock"
          2    "500 500"
          3    "320 240"
          4    "4"


       Example:
        Display(1, "", "Press a mouse button to continue")
        :loop
        buttons = MouseInfo(4)
        If buttons == 0 Then Goto loop
        If buttons & 4 Then Display(1, "", "Left button was pressed")
        If buttons & 1 Then Display(1, "", "Right button was pressed")


       See Also:
          WinMetrics, WinParmGet




       NetAddCon
       Connects network resources to imaginary local disk drives or printer
       ports.


       Syntax:
        NetAddCon (net-path, password, local-name)

       Parameters:
        (s) net-path net resource or string returned by NetBrowse.
        (s) password password required to access resource, or "".





        (s) local-name     local drive name or printer port.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       You can use NetAddCon to connect a local drive to a network directory,
       in which case "local-name" will be a drive name (eg, "Z:").  You can
       also connect a local printer port to a network print queue, in which
       case "local-name" will be the name of the printer port (eg, "LPT1").

       Use the NetBrowse function to obtain a value for "net-path".

       If no password is required, use a null string ("") for the "password"
       parameter.


       Example:
        availdrive = DiskScan(0)
        drvlen = StrLen(availdrive)
        If drvlen == 0 Then Goto nomore
        availdrive = StrSub(availdrive, drvlen - 2, 2)
        netpath = NetBrowse(0)
        pwd = AskPassword("Enter password for", netpath)
        NetAddCon(netpath, pwd, availdrive)
        Exit
        :nomore
        Message("Connect Drive to Net", "No drives avail for assignment")


       See Also:
          NetAttach, NetBrowse, NetCancelCon, NetGetCon, NetMapRoot




       NetAttach
       Attaches to a network file server.


       Syntax:
        NetAttach (server-name)

       Parameters:
        (s) server-name    name of the network file server.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetAttach("userapps")


       See Also:
          NetAddCon, NetDetach, NetLogin








       NetBrowse
       Displays a network dialog box allowing the user to select a network
       resource.


       Syntax:
        NetBrowse (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (s)          see below.

       Specifying a request# of 0 allows selection of a network directory,
       and specifying a request# of 1 allows selection of a network print
       queue.  This function returns a string that can be used by NetAddCon
       to add a connection.


       Example:
        availdrive = DiskScan(0)
        drvlen = StrLen(availdrive)
        If drvlen == 0 Then Goto nomore
        availdrive = StrSub(availdrive, drvlen - 2, 2)
        netpath = NetBrowse(0)
        pswd = AskPassword("Enter password for", netpath)
        NetAddCon(netpath, pswd, availdrive)
        Exit
        :nomore
        Message("Connect Drive to Net", "No drives avail for assignment")


       See Also:
          NetAddCon, NetMapRoot




       NetCancelCon
       Breaks a network connection.


       Syntax:
        NetCancelCon (name, force)

       Parameters:
        (s) name     network resource name or local name.
        (i) force    force flag (see below).

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.





       If force is set to 0, NetCancelCon will not break the connection if
       any files on that connection are still open.  If force is set to 1,
       the connection will be broken regardless.


       Example:
        availdrive = DiskScan(4)
        n = ItemCount(availdrive, " ")
        If n == 0 Then Exit
        i = 1
        dislist = ""
        :loop
        drv = ItemExtract(i, availdrive, " ")
        dislist = StrCat(drv, Num2Char(9), NetGetCon(drv), "|")
        i = i + 1
        If i < n Then Goto loop
        availdrive = ItemSelect("Disconnect", dislist, "|")
        NetCancelCon(availdrive, 0)


       See Also:
          NetAddCon, NetDetach, NetGetCon




       NetDetach
       Detaches from a network file server.


       Syntax:
        NetDetach (server-name)

       Parameters:
        (s) server-name    name of the network file server.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetDetach("userapps")


       See Also:
          NetAttach, NetCancelCon




       NetDialog
       Brings up the network driver's dialog box.






       Syntax:
        NetDialog ( )

       Parameters:
        (none)

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       A network driver's dialog box displays copyright information, and may
       allow access to the network, depending on the particular network
       driver.  The WIL program will wait until the network dialog terminates
       before continuing.


       Example:
        NetDialog()



       NetGetCaps
       Returns information on network capabilities.


       Syntax:
        NetGetCaps (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (i)          see below.

       NetGetCaps returns 0 if no network is installed (it is the only
       network function you can use without having a network installed and
       not get an error).

          Req# Return value

          1    Network driver specification number

          2    Type of network installed:
               0    None
               256  MS Network
               512  Lan Manager
               768  Novell NetWare
               1024 Banyan Vines
               1280 10 Net
               (other)Other network

          3    Network driver version number

          4    Returns 1 if any network is installed

          6    Bitmask indicating whether the network driver supports the
          following





               connect functions:
               1    AddConnection
               2    CancelConnection
               4    GetConnection
               8    AutoConnect via DOS
               16   BrowseDialog

          7    Bitmask indicating whether the network driver supports the
          following
               print functions:
               2    Open Print Job
               4    Close Print Job
               16   Hold Print Job
               32   Release Print Job
               64   Cancel Print Job
               128  Set number of copies
               256  Watch Print Queue
               512  Unwatch Print Queue
               1024 Lock Queue Data
               2048 Unlock Queue Data
               4096 Driver will send QueueChanged messages to Print Manager
               8192 Abort Print Job


       Example:
        caps = NetGetCaps(6)
        If caps & 16 Then Message("", "Your network supports BrowseDialog")

       See Also:
          NetGetUser, WinConfig, WinMetrics, WinParmGet




       NetGetCon
       Returns the name of a connected network resource.


       Syntax:
        NetGetCon (local-name)

       Parameters:
        (s) local-name     local drive name or printer port.

       Returns:
        (s)          name of network resource.

       NetGetCon returns the name of the network resource currently connected
       to "local-name".


       Example:
        local = AskLine("NetGetCon", "Enter local drive name", "")
        If local == "" Then Exit
        resource = NetGetCon(local)
        Message("NetGetCon", "%local% is connected to %resource%")






       See Also:
          NetAddCon, NetCancelCon




       NetGetUser
       Returns the name of the user currently logged into the network.


       Syntax:
        NetGetUser ( )

       Parameters:
        (none)

       Returns:
        (s)          name of current user.


       Example:
        IniWritePvt("Current Users", "Excel", NetGetUser(), "usagelog.ini")
        Run("excel.exe", "")


       See Also:
          NetGetCaps




       NetLogin
       Performs a network login.


       Syntax:
        NetLogin (server-name, user-name, password)

       Parameters:
        (s) server-name    name of the network file server.
        (s) user-name name of the current user.
        (s) password password required to access server, or "".

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        pwd = AskPassword("Hello", "Enter password for network access")
        NetLogin("userapps", "admin1", pwd)


       See Also:
          NetAttach, NetLogout








       NetLogout
       Performs a network logout.


       Syntax:
        NetLogout (server-name)

       Parameters:
        (s) server-name    name of the network file server.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetLogout("userapps")


       See Also:
          NetLogin




       NetMapRoot
       Maps a local drive to a network resource.


       Syntax:
        NetMapRoot (local-name, net-path)

       Parameters:
        (s) local-name     local drive name.
        (s) net-path net resource or string returned by NetBrowse.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function maps a local drive letter as the fake root to a network
       resource.  This is supported by Novell NetWare, but may not work with
       any other networks.






       Example:
        availdrive = DiskScan(0)
        drvlen = StrLen(availdrive)
        If drvlen == 0 Then Goto nomore
        availdrive = StrSub(availdrive, drvlen - 2, 2)
        netpath = NetBrowse(0)
        NetMapRoot(availdrive, netpath)
        Exit
        :nomore
        Message("Connect Drive to Net", "No drives avail for assignment")


       See Also:
          NetAddCon, NetBrowse, NetCancelCon




       NetMemberGet
       Determines whether the current user is a member of a specific group.


       Syntax:
        NetMemberGet (server-name, group-name)

       Parameters:
        (s) server-name    name of the network file server.
        (s) group-name     name of the group.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        member = NetMemberGet("userapps", "sales")
        If member == @YES Then Run("notepad.exe", "dailyrpt.txt")


       See Also:
          NetMemberSet




       NetMemberSet
       Sets the current user as a member of a group.


       Syntax:
        NetMemberSet (server-name, group-name)

       Parameters:
        (s) server-name    name of the network file server.
        (s) group-name     name of the group.






       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetMemberSet("userapps", "sales")


       See Also:
          NetMemberGet




       NetMsgAll
       Broadcasts a message to all users on the network.


       Syntax:
        NetMsgAll (server-name, message)

       Parameters:
        (s) server-name    name of the network file server.
        (s) message  message to be broadcast.

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetMsgAll("userapps", "System going down in 5 minutes.")


       See Also:
          NetMsgSend




       NetMsgSend
       Sends a message to a specific user on the network.


       Syntax:
        NetMsgSend (server-name, user-name, message)

       Parameters:
        (s) server-name    name of the network file server.
        (s) user-name name of the user to whom the message should be sent.
        (s) message  message to be sent.






       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       This function may not work with all networks.


       Example:
        NetMsgSend("userapps", "compmgr", "Are those reports ready yet?")


       See Also:
          NetMsgAll




       Num2Char
       Converts a number to its character equivalent.


       Syntax:
        Num2Char (integer)

       Parameters:
        (i) number   any number from 0 to 255.

       Returns:
        (s)          one-byte string containing the character which the
                     number represents.

       Use this function to convert a number to its ASCII equivalent.


       Example:
        ; Build a variable containing a CRLF combo
        crlf = StrCat(Num2Char(13), Num2Char(10))
        Message("NUM2CHAR", StrCat("line1", crlf, "line2"))


       See Also:
          Char2Num, IsNumber




       ParseData
       Parses the passed string.


       Syntax:
        ParseData (string)

       Parameters:
        (s) string   string to be parsed.






       Returns:
        (i)          number of parameters in string.

       This function breaks a string constant or string variable into new
       sub-string variables named param1, param2, etc. (maximum of nine
       parameters).  Blank spaces in the original string are used as
       delimiters to create the new variables.

       Param0 is the count of how many sub-strings are found in "string".


       Example:
        username = AskLine("Hello", "Please enter your name","")
        ParseData(username)

       If the user enters:

          Joe Q. User

       ParseData would create the following variables:

          param1 ==   Joe
          param2 ==   Q.
          param3 ==   User
          param0 ==   3


       See Also:
          ItemExtract, StrSub




       Pause
       Provides a message to user.  User may cancel processing.


       Syntax:
        Pause (title, text)

       Parameters:
        (s) title    title of pause box.
        (s) text     text of the message to be displayed.

       Returns:
        (i)          always 1.

       This function displays a message to the user with an exclamation point
       icon.  The user may respond by selecting the OK button, or may cancel
       the processing by selecting Cancel.

       The Pause function is similar to the Message function, except for the
       addition of the Cancel button and icon.






       Example:
        Pause("Change Disks", "Insert new disk into Drive A:")

       which produces:










       See Also:
          Display, Exit, Message, Terminate




       PlayMedia
       Controls multimedia devices.


       Syntax:
        PlayMedia (command-string)

       Parameters:
        (s) command-string string to be sent to the multimedia device.

       Returns:
        (s)          response from the device.

       If the appropriate Windows multimedia extensions are present, this
       function can control multimedia devices.  Valid command strings depend
       on the multimedia devices and drivers installed.  The basic Windows
       multimedia package has a waveform device to play and record waveforms,
       and a sequencer device to play MID files.  Refer to the appropriate
       documentation for information on command strings.

       Many multimedia devices accept the WAIT or NOTIFY parameters as part
       of the command string:

          WAIT      Causes the system to stop processing input until the
                    requested operation is complete.  You cannot switch
          tasks     when WAIT is specified.

          NOTIFY    Causes the WIL program to suspend execution until the
                    requested operation completes.  You can perform other
                    tasks and switch between tasks when NOTIFY is specified.

          WAIT NOTIFY Same as WAIT

       If neither WAIT nor NOTIFY is specified, the multimedia operation is
       started and control returns immediately to the WIL program.





       In general, if you simply want the WIL program to wait until the
       multimedia operation is complete, use the NOTIFY keyword.  If you want
       the system to hang until the operation is complete, use WAIT.  If you
       just want to start a multimedia operation and have the program
       continue processing, don't use either keyword.

       The return value from PlayMedia is whatever string the driver returns.
       This will depend on the particular driver, as well as on the type of
       operation performed.


       Example:
        ; Plays a music CD on a CDAudio player.  It plays whatever is in the
        ; drive, from start to finish
        stat = PlayMedia("status cdaudio mode")
        answer = 1
        If stat == "playing" Then answer = AskYesNo("CD Audio", "CD is
            Playing.  Stop?")
        If answer == 0 Then Exit
        PlayMedia("open cdaudio shareable alias donna notify")
        PlayMedia("set donna time format tmsf")
        PlayMedia("play donna from 1")
        PlayMedia("close donna")
        Exit
        :cancel
        PlayMedia("set cdaudio door open")


       See Also:
          Beep, PlayMidi, PlayWaveForm, Sounds




       PlayMidi
       Plays a MID or RMI sound file.


       Syntax:
        PlayMidi (filename, mode)

       Parameters:
        (s) filename name of the MID or RMI sound file.
        (i) mode     play mode (see below).

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       If Windows multimedia sound extensions are present, and MIDI-
       compatible hardware is installed, this function will play a MID or RMI
       sound file.  If "filename" is not in the current directory and a
       directory is not specified, the path will be searched to find the
       file.

       If "mode" is set to 0, the WIL program will wait for the sound file to
       complete before continuing.  If "mode" is set to 1, it will start
       playing the sound file and continue immediately.






       Example:
        PlayMidi("canyon.mid", 1)


       See Also:
          Beep, PlayMedia, PlayWaveForm, Sounds




       PlayWaveForm
       Plays a WAV sound file.


       Syntax:
        PlayWaveForm (filename, mode)

       Parameters:
        (s) filename
        (i) mode     play mode (see below).

       Returns:
        (i)          @TRUE if successful; @FALSE if unsuccessful.

       If Windows multimedia sound extensions are present, and waveform-
       compatible hardware is installed, this function will play a WAV sound
       file.  If "filename" is not in the current directory and a directory
       is not specified, the path will be searched to find the file.  If
       "filename is not found, the WAV file associated with the
       "SystemDefault" keyword is played, (unless the "NoDefault" setting is
       on).

       Instead of specifying an actual filename, you may specify a keyword
       name from the [Sound] section of the WIN.INI file (eg, "SystemStart"),
       in which case the WAV file associated with that keyword name will be
       played.

       "Mode" is a bitmask, composed of the following bits:

          Mode Meaning

          0    Wait for the sound to end before continuing.
          1    Don't wait for the sound to end.  Start the sound and
          immediately process more statements.
          2    If sound file not found, do not play a default sound
          9    Continue playing the sound forever, or until a
               PlayWaveForm("", 0) statement is executed
          16   If another sound is already playing, do not interrupt it.
          Just ignore this PlayWaveForm request.

       You can combine these bits using the binary OR operator.

       The command PlayWaveForm("", 0) can be used at any time to stop sound.






       Examples:
        PlayWaveForm("tada.wav", 0)

        PlayWaveForm("SystemDefault", 1 | 16)


       See Also:
          Beep, PlayMedia, PlayMidi, Sounds




       Random
       Computes a pseudo-random number.


       Syntax:
        Random (max)

       Parameters:
        (i) max      largest desired integer number.

       Returns:
        (i)          unpredictable positive number.

       This function will return a random integer between 0 and max.


       Example:
        a = Random(79)
        Message("Random number between 0 and 79", a)


       See Also:
          Average, Max, Min




       Return
       Used to return from a Call to the calling program.


       Syntax:
        Return

       Parameters:
        (none)

       Returns:
        (not applicable)


       If the program was not called, then an Exit is assumed.






       Example:
        Display(2, "End of subroutine", "Returning to MAIN.WBT")
        Return


       See Also:
          Call, Exit




       Run
       Runs a program as a normal window.


       Syntax:
        Run (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.


       Examples:
        Run("notepad.exe", "abc.txt")

        Run("clock.exe", "")

        Run("paint.exe", "pict.msp")


       See Also:
          AppExist, RunHide, RunIcon, RunWait, RunZoom, WinClose, WinExeName,
          WinWaitClose








       RunHide
       Runs a program as a hidden window.


       Syntax:
        RunHide (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as a hidden window.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it informs it that
       you want it to run as a hidden window.  Whether or not the application
       honors your wish is beyond RunHide's control.


       Examples:
        RunHide("notepad.exe", "abc.txt")

        RunHide("clock.exe", "")

        RunHide("paint.exe", "pict.msp")


       See Also:
          Run, RunHideWait, RunIcon, RunZoom, WinClose, WinExeName, WinHide,
          WinWaitClose




       RunHideWait
       Runs a program as a hidden window, and waits for it to close.






       Syntax:
        RunHideWait (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as a hidden window.  The WIL
       program will suspend processing until the application is closed.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it informs it that
       you want it to run as a hidden window.  Whether or not the application
       honors your wish is beyond RunHideWait's control.


       Example:
        NetAddCon("winword", "", "g:")
        RunHideWait("winword.exe", "")
        NetCancelCon("g:", 0)


       See Also:
          RunHide, RunIconWait, RunWait, RunZoomWait, WinWaitClose




       RunIcon
       Runs a program as an iconic (minimized) window.


       Syntax:
        RunIcon (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.






       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as an icon.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it merely informs it
       that you want it to begin as an icon.  Whether or not the application
       honors your wish is beyond RunIcon's control.


       Examples:
        RunIcon("notepad.exe", "abc.txt")

        RunIcon("clock.exe", "")

        RunIcon("paint.exe", "pict.msp")


       See Also:
          IconArrange, Run, RunHide, RunIconWait, RunZoom, WinClose,
          WinExeName, WinIconize, WinWaitClose




       RunIconWait
       Runs a program as an iconic (minimized) window, and waits for it to
       close.


       Syntax:
        RunIconWait (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as an icon.  The WIL program
       will suspend processing until the application is closed.





       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it merely informs it
       that you want it to begin as an icon.  Whether or not the application
       honors your wish is beyond RunIconWait's control.


       Example:
        NetAddCon("winword", "", "g:")
        RunIconWait("winword.exe", "")
        NetCancelCon("g:", 0)


       See Also:
          IconArrange, RunHideWait, RunIcon, RunWait, RunZoomWait,
          WinWaitClose




       RunWait
       Runs a program as a normal window, and waits for it to close.


       Syntax:
        RunWait (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application.  The WIL program will suspend
       processing until the application is closed.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.






       Example:
        NetAddCon("winword", "", "g:")
        RunWait("winword.exe", "")
        NetCancelCon("g:", 0)


       See Also:
          AppWaitClose, Run, RunHideWait, RunIconWait, RunZoomWait,
          WinWaitClose




       RunZoom
       Runs a program as a full-screen (maximized) window.


       Syntax:
        RunZoom (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as a full-screen window.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [Extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it merely informs it
       that you want it to be maximized to full-screen.  Whether or not the
       application honors your wish is beyond RunZoom's control.


       Examples:
        RunZoom("notepad.exe", "abc.txt")

        RunZoom("clock.exe", "")

        RunZoom("paint.exe", "pict.msp")






       See Also:
          Run, RunHide, RunIcon, RunZoomWait, WinClose, WinExeName,
          WinWaitClose, WinZoom




       RunZoomWait
       Runs a program as a full-screen (maximized) window, and waits for it
       to close.


       Syntax:
        RunZoomWait (program-name, parameters)

       Parameters:
        (s) program-name   the name of the desired .EXE, .COM, .PIF, .BAT
                     file, or a data file.
        (s) parameters     optional parameters as required by the
                     application.

       Returns:
        (i)          @TRUE if the program was found;
                     @FALSE if it wasn't.

       Use this command to run an application as a full-screen window.  The
       WIL program will suspend processing until the application is closed.

       If the drive and path are not part of the program name, the current
       directory will be examined first, followed by the Windows and Windows
       System directories, and then the DOS path will be searched to find the
       desired executable file.

       If the "program-name" doesn't have an extension of .EXE, .COM, .PIF,
       or .BAT, it will be run in accordance with whatever is in the
       [Extensions] section of the WIN.INI file.  When this happens, any
       "parameters" you specified are ignored.

       Note:  When this command launches an application, it merely informs it
       that you want it to be maximized to full-screen.  Whether or not the
       application honors your wish is beyond RunZoomWait's control.


       Example:
        NetAddCon("winword", "", "g:")
        RunZoomWait("winword.exe", "")
        NetCancelCon("g:", 0)


       See Also:
          RunHideWait, RunIconWait, RunWait, RunZoom, WinWaitClose








       SendKey
       Sends keystrokes to the active application.


       Syntax:
        SendKey (char-string)

       Parameters:
        (s) char-string    string of regular and/or special characters.

       Returns:
        (i)          always 0.

       This function is used to send keystrokes to the current window, just
       as if they had been entered from the keyboard.  Any alphanumeric
       character, and most punctuation marks and other symbols which appear
       on the keyboard, may be sent simply by placing it in the "char-
       string."  In addition, the following special characters, enclosed in
       "curly" braces, may be placed in "char-string" to send the
       corresponding special characters:

          Key         SendKey equivalent

          ~           {~}
          !           {!}
          ^           {^}
          +           {+}

          Alt         {ALT}
          Backspace   {BACKSPACE} or {BS}
          Caps Lock   {CAPSLOCK}
          Clear       {CLEAR}
          Delete      {DELETE} or {DEL}
          Down Arrow  {DOWN}
          End         {END}
          Enter       {ENTER} or ~
          Escape      {ESCAPE} or {ESC}
          F1 through F16   {F1} through {F16}
          Help        {HELP}
          Home        {HOME}
          Insert      {INSERT} or {INS}
          Left Arrow  {LEFT}
          Num Lock    {NUMLOCK}
          Page Down   {PGDN}
          Page Up     {PGUP}
          Print Screen{PRTSC}
          Right Arrow {RIGHT}
          Space       {SPACE} or {SP}
          Tab         {TAB}
          Up Arrow    {UP}

       To enter an Alt, Control, or Shift key combination, precede the
       desired character with one or more of the following symbols:





          Alt         !
          Control     ^
          Shift       +

       To enter Alt-S:

        SendKey("!S")

       To enter Ctrl-Shift-F7:

        SendKey("^+{F7}")

       You may also repeat a key by enclosing it in braces, followed by a
       space and the total number of repetitions desired.

       To type 20 asterisks:

        SendKey("{* 20}")

       To move the cursor down 8 lines:

        SendKey("{DOWN 8}")

       It is possible to use SendKey to send keystrokes to a DOS application,
       but only if you are running Windows in 386 Enhanced mode.  You would
       then transfer the keystrokes to the DOS application via the Clipboard.
       It is only possible to send standard ASCII characters to DOS
       applications; you cannot send function key or Alt-key combinations.


       Examples:
        ; start Notepad, and use *.* for filenames
        Run("notepad.exe", "")
        SendKey("!FO*.*~")

        ; run DOS batch file which starts our editor
        Run("edit.bat", "")
        ; wait 15 seconds for editor to load
        Delay(15)
        ; send string (with carriage return) to the clipboard
        crlf = StrCat(Num2Char(13), Num2Char(10))
        ClipPut("Hello%crlf%")
        ; paste contents of clipboard to DOS window
        SendKey("!{SP}EP")


       In those cases where you have an application which can accept text
       pasted in from the clipboard, it will often be more efficient to use
       the ClipGet function:

        Run("notepad.exe", "")
        crlf = StrCat(Num2Char(13), Num2Char(10))
        ; copy some text to the clipboard
        ClipPut("Dear Sirs:%crlf%%crlf%")
        ; paste the text into Notepad (using Shift-Ins)
        SendKey("+{INSERT}")






       See Also:
          ClipGet, SKDebug, SnapShot




       SKDebug
       Controls how SendKey works


       Syntax:
        SKDebug (mode)

       Parameters:
        (i) mode     @OFF       Keystrokes sent to application.  No debug
                     file  written.  Default mode.
               @ON         Keystrokes sent to application.  Debug file
                           written.
               @PARSEONLY  Keystrokes not sent to application.  Debug file
                           written.

       Returns:
        (i)    previous SKDebug mode.

       This function allows you to direct the keystrokes generated by your
       SendKey statements to a disk file in addition to, or instead of, the
       application window.  Normally, keystrokes are sent only to the
       application.  If you specify SKDebug (@ON), keystrokes are sent to a
       disk file as well as to the application.  If you specify SKDebug
       (@PARSEONLY), keystrokes are sent only to the disk file, and not to
       the application.  SKDebug (@OFF) returns to the default mode.

       By default, the file which will receive the parsed keystrokes is named
       C:\@@SKDBUG.TXT.  You can override this by making an entry in the
       WWWBATCH.INI file, in the [Main] section, as follows:

          SKDFile=debug.fil

       where debug.fil is the filename, including complete path
       specification, that you want to receive the keystrokes.


       Example:
        Run("notepad.exe", "")
        SKDebug(@ON)
        SendKey("!FO*.*~")
        SKDebug(@OFF)


       See Also:
          Debug, SendKey








       SnapShot
       Takes a snapshot of the screen and pastes it to the clipboard.


       Syntax:
        SnapShot (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (i)          always 0.

          Req# Meaning

          0    Take snapshot of entire screen
          1    Take snapshot of client area of parent window of active window
          2    Take snapshot of entire area of parent window of active window
          3    Take snapshot of client area of active window
          4    Take snapshot of entire area of active window


       Example:
        SnapShot(2)


       See Also:
          ClipPut




       Sounds
       Turns sounds on or off.


       Syntax:
        Sounds (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (i)          previous Sound setting.

       If Windows multimedia sound extensions are present, this function
       turns sounds made by the WIL Interpreter on or off.  Specify a
       request# of 0 to turn sounds off, and a request# of 1 to turn them on.

       By default, the WIL Interpreter makes noise.  You can override this by
       entering:

          Sounds=0





       in the [Main] section of the WWWBATCH.INI file.


       Example:
        Sounds(0)

       See Also:
          Beep, PlayMedia, PlayMidi, PlayWaveForm




       StrCat
       Concatenates two or more strings.


       Syntax:
        StrCat (string1, string2[, ..., stringN])

       Parameters:
        (s) string1, etc.  at least two strings you want to concatenate.

       Returns:
        (s)          concatenation of the entire list of input strings.

       Use this command to stick character strings together, or to format
       display messages.


       Example:
        user = AskLine("Login", "Your Name:", "")
        msg = StrCat("Hi, ", user)
        Message("Login", msg)

        ; note that this is the same as the second line above:
        msg = "Hi, %user%"


       See Also:
          StrFill, StrFix, StrTrim




       StrCmp
       Compares two strings.


       Syntax:
        StrCmp (string1, string2)

       Parameters:
        (s) string1, string2    strings to compare.

       Returns:
        (i)          -1, 0, or 1; depending on whether string1 is less than,
                     equal to, or greater than string2, respectively.






       Use this command to determine whether two strings are equal, or which
       precedes the other in an ANSI sorting sequence.

       Note:  This command has been included for semantic completeness.  The
       relational operators >, >=, ==, !=, <=, and < provide the same
       capability.


       Example:
        a = AskLine("STRCMP", "Enter a test line", "")
        b = AskLine("STRCMP", "Enter another test line", "")
        c = StrCmp(a, b)
        c = c + 1
        d = StrSub("less than   equal to    greater than", c * 12, 12)
        ; Note that above string is grouped into 12-character
        ; chunks.
        ; Desired chunk is removed with the StrSub statement.
        Message("STRCMP", "%a% is %d% %b%")


       See Also:
          StriCmp, StrIndex, StrLen, StrScan, StrSub




       StrFill
       Creates a string filled with a series of characters.


       Syntax:
        StrFill (filler, length)

       Parameters:
        (s) filler   a string to be repeated to create the return string.  If
                     the filler string is null, spaces will be used instead.
        (i) length   the length of the desired string.

       Returns:
        (s)          character string.

       Use this function to create a string consisting of multiple copies of
       the filler string concatenated together.


       Example:
        Message("My Stars", StrFill("*", 30))

       which produces:






       See Also:
          StrCat, StrFix, StrLen, StrTrim




       StrFix
       Pads or truncates a string to a fixed length.


       Syntax:
        StrFix (base-string, pad-string, length)

       Parameters:
        (s) base-string    string to be adjusted to a fixed length.
        (s) pad-string     appended to base-string if needed to fill out the
                     desired length.  If pad-string is null, spaces are used
                     instead.
        (i) length   length of the desired string.

       Returns:
        (s)          fixed size string.

       This function "fixes" the length of a string, either by truncating it
       on the right, or by appending enough copies of pad-string to achieve
       the desired length.


       Example:
        a = StrFix("Henry", " ", 15)
        b = StrFix("Betty", " ", 15)
        c = StrFix("George", " ", 15)
        Message("Spaced Names", StrCat(a, b, c))

       which produces:









       See Also:
          StrFill, StrLen, StrTrim




       StriCmp
       Compares two strings without regard to case.


       Syntax:
        StriCmp (string1, string2)






       Parameters:
        (s) string1, string2    strings to compare.

       Returns:
        (i)          -1, 0, or 1; depending on whether string1 is less than,
                     equal to, or greater than string2, respectively.

       Use this command to determine whether two strings are equal, or which
       precedes the other in an ANSI sorting sequence, when case is ignored.


       Example:
        a = AskLine("STRICMP", "Enter a test line", "")
        b = AskLine("STRICMP", "Enter another test line", "")
        c = StriCmp(a, b)
        c = c + 1
        d = StrSub("less than   equal to    greater than", c * 12, 12)
        ; Note that above string is grouped into 12-character
        ; chunks.
        ; Desired chunk is removed with the StrSub statement.
        Message("STRICMP", "%a% is %d% %b%")


       See Also:
          StrCmp, StrIndex, StrLen, StrScan, StrSub




       StrIndex
       Searches a string for a substring.


       Syntax:
        StrIndex (string, substring, start, direction)

       Parameters:
        (s) string   the string to be searched for a substring.
        (s) substring the string to look for within the main string.
        (i) start    the position in the main string to begin search.  The
                     first character of a string is position 1.
        (i) direction the search direction.  @FWDSCAN searches forward, while
                     @BACKSCAN searches backwards.

       Returns:
        (i)          position of substring within string, or 0 if not found.

       This function searches for a substring within a "target" string.
       Starting at the "start" position, it goes forward or backward
       depending on the value of the "direction" parameter.  It stops when it
       finds the "substring" within the "target" string, and returns its
       position.

       A start position of 0 has special meaning depending on which direction
       you are scanning.  For forward searches, zero indicates the search





       should start at the beginning of the string.  For reverse searches,
       zero causes it to start at the end of the string.


       Example:
        instr = AskLine("STRINDEX", "Type a sentence:", "")
        start = 1
        end = StrIndex(instr, " ", start, @FWDSCAN)
        If end == 0 Then Goto error
        Message("STRINDEX", StrCat("The first word is: ", StrSub(instr,
            start, end - 1))
        Exit
        :error
        Message("Sorry...", "No spaces found")


       See Also:
          StrLen, StrScan, StrSub




       StrLen
       Provides the length of a string.


       Syntax:
        StrLen (string)

       Parameters:
        (s) string   any text string.

       Returns:
        (i)          length of string.

       Use this command to determine the length of a string variable or
       expression.


       Example:
        myfile = AskLine("Filename", "File to process:", "")
        namlen = StrLen(myfile)
        If namlen > 13 Then Message("", "Filename too long!")


       See Also:
          StrFill, StrFix, StrIndex, StrScan, StrTrim




       StrLower
       Converts a string to lowercase.


       Syntax:
        StrLower (string)






       Parameters:
        (s) string   any text string.

       Returns:
        (s)          lowercase string.

       Use this command to convert a text string to lower case.


       Example:
        a = AskLine("STRLOWER", "Enter text", "")
        b = StrLower(a)
        Message(a, b)


       See Also:
          StriCmp, StrUpper




       StrReplace
       Replaces all occurances of a substring with another.


       Syntax:
        StrReplace (string, old, new)

       Parameters:
        (s) string   string in which to search.
        (s) old      target substring.
        (s) new      replacement substring.

       Returns:
        (s)          updated string, with old replaced by new.


       StrReplace scans the "string", searching for occurrences of "old" and
       replacing each occurrence with "new".


       Example:
        ; Copy all INI files to clipboard
        a = FileItemize("*.ini")
        crlf = StrCat(Num2Char(13), Num2Char(10))
        b = StrReplace(a, " ", crlf)
        ClipPut(b)


       See Also:
          StrIndex, StrScan, StrSub








       StrScan
       Searches string for occurrence of delimiters.


       Syntax:
        StrScan (string, delimiters, start, direction)

       Parameters:
        (s) string   the string that is to be searched.
        (s) delimiters     a string of delimiters to search for within
                     string.
        (i) start    the position in the main string to begin search.  The
                     first character of a string is position 1.
        (i) direction the search direction.  @FWDSCAN searches forward, while
                     @BACKSCAN searches backwards.

       Returns:
        (i)          position of delimiter in string, or 0 if not found.

       This function searches for delimiters within a target "string".
       Starting at the "start" position, it goes forward or backward
       depending on the value of the "direction" parameter.  It stops when it
       finds any one of the characters in the "delimiters" string within the
       target "string".


       Example:
        thestr = "123,456.789:abc"
        start = 1
        end = StrScan(thestr, ",.:", start, @FWDSCAN)
        If end == 0 Then Goto error
        Message("The first parameter", StrSub(thestr, start, end -      start
        + 1))
        Exit
        :error
        Message("Sorry...", "No delimiters found")


       See Also:
          StrLen, StrSub




       StrSub
       Extracts a substring out of an existing string.


       Syntax:
        StrSub (string, start, length)

       Parameters:
        (s) string   the string from which the substring is to be extracted.





        (i) start    character position within string where the substring
                     starts.  (The first character of the string is at
                     position 1).
        (i) length   length of desired substring.  If you specify a length of
                     zero it will return a null string.

       Returns:
        (s)          substring of parameter string.

       This function extracts a substring from within a "target" string.
       Starting at the "start" position, it copies up to "length" characters
       into the substring.


       Example:
        a = "My dog has fleas"
        animal = StrSub(a, 4, 3)
        Message("STRSUB", "My animal is a %animal%")


       See Also:
          StrLen, StrScan




       StrTrim
       Removes leading and trailing blanks from a character string.


       Syntax:
        StrTrim (string)

       Parameters:
        (s) string   a string with unwanted spaces at the beginning and/or
                     end.

       Returns:
        (s)          string devoid of leading and trailing spaces.

       This function removes spaces and tab characters from the beginning and
       end of a text string.


       Example:
        myfile = AskLine("STRTRIM", "Filename ('exit' cancels)", "")
        tstexit = StrTrim(StrLower(myfile))
        If tstexit == "exit" Then Goto cancel
        ; processing of myfile continues...
        : cancel
        Message("Canceled", "...by user request")


       See Also:
          StrFill, StrFix, StrLen








       StrUpper
       Converts a string to uppercase.


       Syntax:
        StrUpper (string)

       Parameters:
        (s) string   any text string.

       Returns:
        (s)          uppercase string.

       Use this function to convert a text string to upper case.


       Example:
        a = AskLine("STRUPPER", "Enter text","")
        b = StrUpper(a)
        Message(a, b)


       See Also:
          StriCmp, StrLower




       Terminate
       Conditionally ends a WIL program.


       Syntax:
        Terminate (expression, title, message)

       Parameters:
        (s) expression     any logical expression.
        (s) title    the title of a message box to be displayed before
                     termination.
        (s) message  the message in the message box.

       Returns:
        (i)          always 1.

       This command ends processing for the WIL program if "expression" is
       nonzero.  Note that many functions return @TRUE (1) or @FALSE (0),
       which you can use to decide whether to cancel a menu item.

       If either "title" or "message" contains a string, a message box with a
       title and a message is displayed before exiting.






       Examples:
        ; unconditional termination w/o message box (same as Exit)
        Terminate(@TRUE, "", "")

        ; basically a no-op:
        Terminate(@FALSE, "", "This will never terminate")

        ; exits with message if variable is less than zero:
        Terminate(a < 0, "Error", "Cannot use negative numbers")

        ; exits w/o message if answer isn't "YES":
        Terminate(answer != "YES", "", "")


       See Also:
          Display, Exit, Message, Pause




       TextBox
       Displays a file in a listbox on the screen and returns selected line,
       if any.


       Syntax:
        TextBox (title, filename)

       Parameters:
        (s) title    listbox title.
        (s) filename file containing contents of listbox.

       Returns:
        (s)          highlighted string, if any.

       This function loads a file into a Windows listbox and displays the
       listbox to the user.  TextBox has two primary uses:  First, it can be
       used to display multi-line messages to the user.  In addition, because
       of its ability to return a selected line, it may be used as a multiple
       choice question box.  The line highlighted by the user (if any) will
       be returned to the program.

       If disk drive and path not are part of the filename, the current
       directory will be examined first, and then the DOS path will be
       searched to find the desired file.


       Example:
        ; Display WIN.INI
        a = TextBox("Choose a line", "c:\windows\win.ini")
        Display(3, "Chosen line", a)

       which produces (at least on my system):





















       and then:







       See Also:
          ItemSelect, TextSelect




       TextSelect
       Allows the user to choose an item from an unsorted listbox.


       Syntax:
        TextSelect (title, list, delimiter)

       Parameters:
        (s) title    the title of dialog box to display.
        (s) list     a string containing a list of items to choose from.
        (s) delimiter a string containing the character to act as delimiter
                     between items in the list.

       Returns:
        (s)          the selected item.

       This function displays a dialog box with a listbox inside.  This
       listbox is filled with an unsorted list of items taken from a string
       you provide to the function.

       Each item in the string must be separated (delimited) by a character,
       which you also pass to the function.

       The user selects one of the items by either doubleclicking on it, or
       single-clicking and pressing OK.  The item is returned as a string.





       If you create the list with the FileItemize or DirItemize functions
       you will be using a space-delimited list.  WinItemize, however,
       creates a tab-delimited list of window titles since titles can have
       embedded blanks.

       TextSelect is like ItemSelect, except that with TextSelect the
       displayed box is larger and the items in the box are not sorted
       alphabetically.


       Example:
        DirChange(DirWindows(0))
        inifiles = FileItemize("*.ini")
        ini = TextSelect("Select an INI file to edit", inifiles, " ")
        If ini == "" Then Exit
        RunZoom("notepad.exe", ini)


       See Also:
          AskLine, DialogBox, DirItemize, FileItemize, ItemSelect, TextBox,
          WinItemize




       Then
       Continues a previous If statement.


       Syntax:
        Then statement

       Parameters:
        (s) statement any valid WIL function or command.

       This command continues the last-encountered If command.  It provides a
       method of conditionally executing multiple statements, without having
       to test the condition more than once.  If the previous If condition
       was true, the statement following the Then keyword is executed.  If
       the previous If condition was false, the statement following the Then
       keyword is ignored.




       Example:
        answer = AskYesNo("Financial Management", "Run WinCheck now?")
        If answer == @YES Then DirChange("c:\win\check")
        Then Run("wincheck.exe", "")
        Then WinWaitClose("WinCheck")
        Message("Okay", "Processing complete")


       See Also:
          Else, Goto, If ... Then








       Version
       Returns the version number of the parent program currently running.


       Syntax:
        Version ( )

       Parameters:
        (none)

       Returns:
        (s)          parent program version number.

       Use this function to determine the version of the parent program that
       is currently running.


       Example:
        ver = Version()
        Message("Version number", ver)


       See Also:
          DOSVersion, Environment, VersionDLL WinVersion




       VersionDLL
       Returns the version number of the WIL Interpreter currently running.


       Syntax:
        VersionDLL ( )

       Parameters:
        (none)

       Returns:
        (s)          WIL Interpreter version number.

       Use this function to determine the version of the WIL Interpreter that
       is currently running.  It is useful to verify that a WIL program
       generated with the latest version of the language will operate
       properly on what may be a different machine with a different version
       of the WIL Interpreter installed.






       Example:
        ver = VersionDLL()
        If ver >= "1.0c" Then Goto proceed
        Message("Sorry", "WIL Interpreter version 1.0c or higher required")
        Exit
        :proceed
        NetDialog()


       See Also:
          DOSVersion, Environment, Version, WinVersion




       WaitForKey
       Waits for a specific key to be pressed.


       Syntax:
        WaitForKey (key1, key2, key3, key4, key5)

       Parameters:
        (s) key1 - key5    five keystrokes to wait for.

       Returns:
        (i)          position of the selected keystroke (1-5).

       WaitForKey requires five parameters, each of which represents a
       keystroke (refer to the SendKey function for a list of special
       keycodes which can be used).  The WIL program will be suspended until
       one of the specified keys are pressed, at which time the WaitForKey
       function will return a number from 1 to 5, indicating the position of
       the "key" that was selected, and the program will continue.  You can
       specify a null string ("") for one or more of the "key" parameters if
       you don't need to use all five.

       WaitForKey will detect its keystrokes in most, but not all, Windows
       applications.  Any keystroke that is pressed is also passed on to the
       underlying application.


       Example:
        k = WaitForKey("{F11}", "{F12}", "{INSERT}", "", "")
        If k == 1 Then Message("WaitForKey", "You pressed the F11 key")
        If k == 2 Then Message("WaitForKey", "You pressed the F12 key")
        If k == 3 Then Message("WaitForKey", "You pressed the Insert key")


       See Also:
          IgnoreInput, IsKeyDown








       WallPaper
       Changes the Windows wallpaper.


       Syntax:
        WallPaper (bmp-name, tile)


       Parameters:
        (s) bmp-name Name of the BMP wallpaper file.
        (i) tile     @TRUE if wallpaper should be tiled;
                     @FALSE if wallpaper should not be tiled.

       Returns:
        (i)          always 0.

       This function immediately changes the Windows wallpaper.  It can even
       be used for wallpaper "slide shows."


       Example:
        DirChange("c:\windows")
        a = FileItemize("*.bmp")
        a = ItemSelect("Select New paper", a, " ")
        tile = @FALSE
        If FileSize(a) < 40000 Then tile = @TRUE
        Wallpaper(a, tile)


       See Also:
          WinParmSet




       WinActivate
       Activates a previously running window.


       Syntax:
        WinActivate (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be activated.

       Returns:
        (i)          @TRUE if a window was found to activate;
                     @FALSE if no windows were found.

       Use this function to activate windows for user input.






       Example:
        Run("notepad.exe", "")
        Run("clock.exe", "")
        WinActivate("Notepad")


       See Also:
          WinCloseNot, WinGetActive, WinName, WinShow




       WinArrange
       Arranges, tiles, and/or stacks application windows.


       Syntax:
        WinArrange (style)

       Parameters:
        (i) style    one of the following: @STACK, @TILE (or @ARRANGE),
                     @ROWS, or @COLUMNS.

       Returns:
        (i)          always 1.

       Use this function to rearrange the open windows on the screen.  (Any
       iconized programs are unaffected.)

       If there are more than four open windows and you specify @ROWS, or if
       there are more than three open windows and you specify @COLUMNS, @TILE
       will be used instead.


       Example:
        ; Reveal all windows
        WinArrange(@TILE)


       See Also:
          IconArrange, WinHide, WinIconize, WinItemize, WinPlace, WinShow,
          WinZoom




       WinClose
       Closes an open window.


       Syntax:
        WinClose (partial-winname)






       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be closed.

       Returns:
        (i)          @TRUE if a window was found to close;
                     @FALSE if no windows were found.

       Use this function to close windows.

       WinClose will not close the window which contains the currently-
       executing WIL file.  You can, however, use EndSession to end the
       current Windows session.


       Example:
        Run("notepad.exe", "")
        WinClose("Notepad")


       See Also:
          EndSession, WinCloseNot, WinHide, WinIconize, WinItemize,
          WinWaitClose




       WinCloseNot
       Closes all windows, except those provided as parameters.


       Syntax:
        WinCloseNot (partial-winname [, partial-winname...])

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  Any windows whose titles match the partial
                     names will stay open.

       Returns:
        (i)          always 1.

       Use this function to close all windows except those specifically
       listed in the parameter strings.

       At least one partial window name must be given.  A null-string
       parameter would match all windows, or, in other words, close nothing.


       Example:
        ; The statement below will close all windows except:
        ; 1) Program Manager (starts with 'Program')
        ; 2) Clock  (starts with 'Clo' )
        WinCloseNot("Program", "Clo")






       See Also:
          EndSession, WinClose, WinHide, WinIconize, WinItemize, WinWaitClose




       WinConfig
       Returns WIN3 mode flags.


       Syntax:
        WinConfig ( )

       Parameters:
        (none)

       Returns:
        (i)          sum of Windows configuration bits.


       Returns Windows configuration information as a number, which is the
       sum of the following individual bits:

          1    Protected Mode
          2    80286 CPU
          4    80386 CPU
          8    80486 CPU
          16   Standard Mode
          32   Enhanced Mode
          64   8086 CPU
          128  80186 CPU
          256  Large PageFrame
          512  Small PageFrame
          1024 80x87 Installed

       You will need to use bitwise operators to extract the individual bits.


       Examples:
        cfg = WinConfig()
        If cfg & 32 Then Display(2, "Windows Mode", "Enhanced Mode")
        If cfg & 16 Then Display(2, "Windows Mode", "Standard Mode")
        If !(cfg & 1) Then Display(2, "Windows Mode", "Real Mode")

        cfg = WinConfig()
        If cfg & 1024 Then Display(2, "Math co-processor", "Yes")
        If !(cfg & 1024) Then Display(2, "Math co-processor", "No")

       See Also:
          NetGetCaps, WinMetrics, WinParmGet, WinResources








       WinExeName
       Returns the name of the executable file which created a specified
       window.


       Syntax:
        WinExeName (partial-winname)

       Parameters:
        (s) partial-winname     the initial part of, or an entire, window
                     name.

       Returns:
        (s)          name of the EXE file.

       Returns the name of the EXE file which created the first window found
       whose title matches "partial-winname".

       "Partial-winname" is the initial part of a window name, and may be a
       complete window name.  It is case-sensitive.  You should specify
       enough characters so that "partial-winname" matches only one existing
       window.


       Example:
        prog = WinExeName("WinCheck")
        WinClose("WinCheck")
        Delay(5)
        Run(prog, "")


       See Also:
          AppExist, AppWaitClose, Run, WinExist, WinGetActive, WinName




       WinExist
       Tells if specified window exists.


       Syntax:
        WinExist (partial-winname)

       Parameters:
        (s) partial-winname     the initial part of, or an entire, window
                     name.

       Returns:
        (i)          @TRUE if a matching window is found;
                     @FALSE if a matching window is not found.





       Note: The partial window name you give must match the initial portion
       of the window name (as appears in the title bar) exactly, including
       proper case (upper or lower) and punctuation.


       Example:
        If WinExist("Clock") == @FALSE Then RunIcon("Clock", "")

       See Also:
          AppExist, WinActivate, WinClose, WinExeName, WinGetActive,
          WinItemize, WinState




       WinGetActive
       Gets the title of the active window.


       Syntax:
        WinGetActive ( )

       Parameters:
        (none)

       Returns:
        (s)          title of active window.

       Use this function to determine which window is currently active.


       Example:
        currentwin = WinGetActive()


       See Also:
          WinActivate, WinExeName, WinItemize, WinName, WinPlaceGet,
          WinPosition, WinTitle




       WinHide
       Hides a window.


       Syntax:
        WinHide (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be hidden.

       Returns:
        (i)          @TRUE if a window was found to hide;
                     @FALSE if no windows were found.






       Use this function to hide windows.  The programs are still running
       when they are hidden.

       A partial-window name of "" (null string) hides the window making the
       current call to the WIL Interpreter.


       Example:
        Run("notepad.exe", "")
        WinHide("Notepad")
        Delay(3)
        WinShow("Notepad")


       See Also:
          RunHide, WinClose, WinIconize, WinPlace




       WinIconize
       Iconizes a window.


       Syntax:
        WinIconize (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be iconized.

       Returns:
        (i)          @TRUE if a window was found to iconize;
                     @FALSE if no windows were found.

       Use this function to turn a window into an icon at the bottom of the
       screen.

       A partial-window name of "" (null string) iconizes the current WIL
       Interpreter window.


       Example:
        Run("clock.exe", "")
        WinIconize("Clo")  ; partial window name used here


       See Also:
          IconArrange, RunIcon, WinClose, WinHide, WinPlace, WinShow, WinZoom




       WinItemize
       Returns a tab-delimited list of all open windows.






       Syntax:
        WinItemize ( )

       Parameters:
        (none)

       Returns:
        (s)          list of the titles of all open windows.

       This function compiles a list of all the open application windows'
       titles and separates the titles by tabs.  This is especially useful in
       conjunction with the ItemSelect function, which enables the user to
       choose an item from such a tab-delimited list.

       Note this behaves somewhat differently than FileItemize and
       DirItemize, which create space-delimited lists.  This is because
       window titles regularly contain embedded spaces.


       Example:
        ; Find a window
        allwins = WinItemize()
        htab = Num2Char(9)
        mywind = ItemSelect("Windows", allwins, htab)
        WinActivate(mywind)


       See Also:
          DirItemize, FileItemize, ItemSelect, TextSelect, WinClose,
          WinCloseNot, WinGetActive, WinName, WinPlaceGet, WinPosition




       WinMetrics
       Returns Windows system information.


       Syntax:
        WinMetrics (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (i)          see below.

       The request# parameter determines what piece of information will be
       returned.





          Req# Return value
          -1   Number of colors supported by video driver
          0    Width of screen, in pixels
          1    Height of screen, in pixels
          2    Width of arrow on vertical scrollbar
          3    Height of arrow on horizontal scrollbar
          4    Height of window title bar
          5    Width of window border lines
          6    Height of window border lines
          7    Width of dialog box frame
          8    Height of dialog box frame
          9    Height of thumb box on scrollbar
          10   Width of thumb box on scrollbar
          11   Width of an icon
          12   Height of an icon
          13   Width of a cursor
          14   Height of a cursor
          15   Height of a one line menu bar
          16   Width of full screen window
          17   Height of a full screen window
          18   Height of Kanji window (Japanese)
          19   Is a mouse present (0 = No, 1 = Yes)
          20   Height of arrow on vertical scrollbar
          21   Width of arrow on horizontal scrollbar
          22   Is debug version of Windows running (0 = No, 1 = Yes)
          23   Are Left and Right mouse buttons swapped (0 = No, 1 = Yes)
          24   Reserved
          25   Reserved
          26   Reserved
          27   Reserved
          28   Minimum width of a window
          29   Minimum height of a window
          30   Width of bitmaps in title bar
          31   Height of bitmaps in title bar
          32   Width of sizeable window frame
          33   Height of sizeable window frame
          34   Minimum tracking width of a window
          35   Minimum tracking height of a window

       Example:
        mouse = "NO"
        If WinMetrics(19) == 1 Then mouse = "YES"
        Message("Is there a mouse installed?", mouse)


       See Also:
          Environment, MouseInfo, NetGetCaps, WinConfig, WinParmGet,
          WinResources




       WinName
       Returns the name of the window calling the WIL Interpreter.






       Syntax:
        WinName ( )

       Parameters:
        (none)

       Returns:
        (s)          window name.

       Returns the name of the window making the current call to the WIL
       Interpreter.


       Example:
        tab = Num2Char(9)
        allwins = WinItemize()
        win = ItemSelect("Close window", allwins, tab)
        If win == WinName() Then Goto nocando
        WinClose(win)
        Exit
        :nocando
        Message("Sorry", "I can't close myself")


       See Also:
          WinActivate, WinExeName, WinGetActive, WinItemize, WinTitle




       WinParmGet
       Returns system information.


       Syntax:
        WinParmGet (request#)

       Parameters:
        (i) request# see below.

       Returns:
        (s)          see below.

       Note: This function requires Windows 3.1 or higher.

       The request# parameter determines what piece of information will be
       returned.

          Req#   Meaning  Return value





          1 Beeping       0 = Off, 1 = On
          2 Mouse sensitivity   "threshold1 threshold2 speed"
          3 Border Width  Width in pixels
          4 Keyboard Speed Keyboard Repeat rate
          5 LangDriver    name of LANGUAGE.DLL
          6 Horiz. Icon Spacing Spacing in pixels
          7 Screen Save Timeout Timeout in seconds
          8 Is screen saver enabled  0 = No, 1 = Yes
          9 Desktop Grid size   Grid Size
          10Wallpaper BMP file  BMP file name
          11Desktop Pattern     Pattern codes (string of 8 space-delimited
          nums.)
          12Keyboard Delay Delay in milliseconds
          13Vertical Icon Spacing    Spacing in pixels
          14IconTitleWrap 0 = No, 1 = Yes
          15MenuDropAlign 0 = Right, 1 = Left
          16DoubleClickWidth    Allowable horiz. movement in pixels for
          DblClick
          17DoubleClickHeight   Allowable vert. movement in pixels for
          DblClick
          18DoubleClickSpeed    Max time in millisecs between clicks for
          DblClick
          19MouseButtonSwap     0 = Not swapped, 1 = swapped
          20Fast Task Switch    0 = Off, 1 = On


       Example:
        If WinParmGet(8) == 1 Then Message("", "Screen saver is active")


       See Also:
          Environment, MouseInfo, NetGetCaps, WinConfig, WinMetrics,
          WinParmSet, WinResources




       WinParmSet
       Sets system information.


       Syntax:
        WinParmSet (request#, new-value, ini-control)

       Parameters:
        (i) request# see WinParmGet
        (s) new-value see WinParmGet
        (i) ini-control    see below.

       Returns:
        (int)        previous value of the setting.

       Note: This function requires Windows 3.1 or higher.

       See WinParmSet for a list of valid request#'s and values.





       The "ini-control" parameter determines to what extent the value gets
       updated:

          0 Set system value in memory only for future reference
          1 Write new value to appropriate INI file
          2 Broadcast message to all applications informing them of new value
          3 Both 1 and 2


       Example:
        WinParmSet(9, "2", 3)   ; sets desktop grid size to 2


       See Also:
          WallPaper, WinParmGet




       WinPlace
       Places a window anywhere on the screen.


       Syntax:
        WinPlace (x-ulc, y-ulc, x-brc, y-brc, partial-winname)

       Parameters:
        (i) x-ulc    how far from the left of the screen to place the upper-
                     left corner (0-1000).
        (i) y-ulc    how far from the top of the screen to place the upper-
                     left corner (0-1000).
        (i) x-brc    how far from the left of the screen to place the bottom-
                     right corner (10-1000) or @NORESIZE.
        (i) y-brc    how far from the top of the screen to place the bottom-
                     right corner (10-1000) or @NORESIZE or @ABOVEICONS.
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be moved to the new position.

       Returns:
        (i)          @TRUE if a window was found to move;
                     @FALSE if no windows were found.

       Use this function to move windows on the screen.  (You cannot,
       however, move icons or windows that have been maximized to full
       screen.)

       The "x-ulc", "y-ulc", "x-brc", and "y-brc" parameters are based on a
       logical screen that is 1000 points wide by 1000 points high.

       You can move the window without changing the width and/or height by
       specifying @NORESIZE for the "x-brc" and/or "y-brc" parameters,
       respectively.

       You can fix the bottom of the window to sit just above the line of
       icons along the bottom of the screen by specifying a "y-brc" of
       @ABOVEICONS.





       Some sample parameters:

          Upper left quarter of the screen:  0, 0, 500, 500
          Upper right quarter:  500, 0, 1000, 500
          Center quarter:  250, 250, 750, 750
          Lower left eighth:  0, 750, 500, 1000

       A handy utility program is provided, called WININFO.EXE.  This program
       lets you take an open window that is sized and positioned the way you
       like it, and automatically create the proper WinPlace statement for
       you.  It puts the text into the Clipboard, from which you can paste it
       into your program.

       You'll need a mouse to use WinInfo.  While WinInfo is the active
       window, place the mouse over the window you wish to create the
       WinPlace statement for, and press the spacebar.  The new statement
       will be placed into the Clipboard.  Then press the Esc key to close
       WinInfo.


       Example:
        WinPlace(0, 0, 200, 200, "Clock")


       See Also:
          WinArrange, WinHide, WinIconize, WinPlaceSet, WinPosition, WinShow,
          WinZoom




       WinPlaceGet
       Returns window coordinates.


       Syntax:
        WinPlaceGet (win-type, partial-winname)

       Parameters:
        (i) win-type @ICON, @NORMAL, or @ZOOMED
        (s) partial-winname     the initial part of, or an entire, window
                     name.

       Returns:
        (s)          window coordinates (see below).

       This function returns the coordinates for an iconized, normal, or
       zoomed window.

       "Partial-winname" is the initial part of a window name, and may be a
       complete window name.  It is case-sensitive.  You should specify
       enough characters so that "partial-winname" matches only one existing
       window.  If it matches more than one window, the most recently
       accessed window which it matches will be used.

       The returned value is a string of either 2 or 4 numbers, as follows:





          Iconic windows   "x y"     (upper left corner of the icon)
          Normal windows   "upper-x upper-y lower-x lower-y"
          Zoomed windows   "x y"     (upper left corner of the window)

       All coordinates are relative to a virtual 1000x1000 screen.


       Examples:
        Run("clock.exe", "")
        pos = WinPlaceGet(@NORMAL, "Clock")
        Delay(2)
        WinPlaceSet(@NORMAL, "Clock", "250 250 750 750")
        Delay(2)
        WinPlaceSet(@NORMAL, "Clock", pos)


       See Also:
          WinGetActive, WinItemize, WinPlaceSet, WinPosition, WinState




       WinPlaceSet
       Sets window coordinates.


       Syntax:
        WinPlaceSet (win-type, partial-winname, position-string)

       Parameters:
        (i) win-type @ICON, @NORMAL, or @ZOOMED
        (s) partial-winname     the initial part of, or an entire, window
                     name.
        (s) position-string     window coordinates (see below).

       Returns:
        (s)          previous coordinates.

       This function sets the coordinates for an iconized, normal, or zoomed
       window.  The window does not have to be in the desired state to set
       the coordinates; for example, you can set the iconized position for a
       normal window so that when the window is subsequently iconized, it
       will go to the coordinates that you've set.

       "Partial-winname" is the initial part of a window name, and may be a
       complete window name.  It is case-sensitive.  You should specify
       enough characters so that "partial-winname" matches only one existing
       window.  If it matches more than one window, the most recently
       accessed window which it matches will be used.

       "Position-string" is a string of either 2 or 4 numbers, as follows:

          Iconic windows   "x y"     (upper left corner of the icon)
          Normal windows   "upper-x upper-y lower-x lower-y"
          Zoomed windows   "x y"     (upper left corner of the window)

       All coordinates are relative to a virtual 1000x1000 screen.






       Examples:
        WinPlaceSet(@ICON, "Clock", "10 950")

        WinPlaceSet(@NORMAL, "Clock", "250 250 750 750")

        WinPlaceSet(@ZOOMED, "Clock", "-5 -5")


       See Also:
          IconArrange, WinActivate, WinArrange, WinPlace, WinPlaceGet,
          WinState




       WinPosition
       Returns Window position.


       Syntax:
        WinPosition (partial-winname)

       Parameters:
        (s) partial-winname     the initial part of, or an entire, window
                     name.

       Returns:
        (s)          window coordinates, delimited by commas.


       Returns the current window position information for the selected
       window.  It returns 4 comma-separated numbers (see WinPlace for
       details).


       Example:
        Run("clock.exe", "")       ; start Clock
        WinPlace(0,0,300,300, "Clock")    ; place Clock
        pos = WinPosition("Clock") ; save position
        delay(2)
        WinPlace(200,200,300,300, "Clock")     ; move Clock
        delay(2)
        WinPlace(%pos%, "Clock")   ; restore Clock


       See Also:
          WinGetActive, WinItemize, WinPlace, WinPlaceGet, WinState




       WinResources
       Returns information on available memory and resources.






       Syntax:
        WinResources (request#)

       Parameters:
        (i) request# see below

       Returns:
        (i)          see below.

       The value of request# determined the piece of information returned.

          Req#   Return value

          0  Total available memory, in bytes
          1  Theoretical maximum available memory, in bytes
          2  Percent of free system resources (lower of GDI and USER)
          3  Percent of free GDI resources
          4  Percent of free USER resources


       Example:
        mem = WinResources(0)
        Message("Available memory", "%mem% bytes")


       See Also:
          WinConfig, WinMetrics, WinParmGet




       WinShow
       Shows a window in its "normal" state.


       Syntax:
        WinShow (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be shown.

       Returns:
        (i)          @TRUE if a window was found to show;
                     @FALSE if no windows were found.

       Use this function to restore a window to its "normal" size and
       position.

       A partial-window name of "" (null string) restores the current WIL
       interpreter window.






       Example:
        RunZoom("notepad.exe", "")
        ; other processing...
        WinShow("Notepad")


       See Also:
          WinArrange, WinHide, WinIconize, WinZoom




       WinState
       Returns the current state of a window.


       Syntax:
        WinState (partial-winname)

       Parameters:
        (s) partial-winname     the initial part of, or an entire, window
                     name.

       Returns:
        (i)          window state (see below).

       "Partial-winname" is the initial part of a window name, and may be a
       complete window name.  It is case-sensitive.  You should specify
       enough characters so that "partial-winname" matches only one existing
       window.  If it matches more than one window, the most recently
       accessed window which it matches will be used.

       Possible return values are as follows.

          Value Symbolic name   Meaning

          -1                Specified window exists, but is hidden
          0                 Specified window does not exist
          1     @ICON       Specified window is iconic (minimized)
          2     @NORMAL     Specified window is a normal window
          3     @ZOOMED     Specified window is zoomed (maximized)


       Example:
        If WinState("Notepad") == @ICON Then WinShow("Notepad")


       See Also:
          Run, WinExist, WinGetActive, WinHide, WinIconize, WinItemize,
          WinPlace, WinPlaceGet, WinPlaceSet, WinPosition, WinShow, WinZoom




       WinTitle
       Changes the title of a window.






       Syntax:
        WinTitle (partial-winname, new-name)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be shown.
        (s) new-name the new name of the window.

       Returns:
        (i)          @TRUE if a window was found to rename;
                     @FALSE if no windows were found.

       Use this function to change a window's title.

       A partial-window name of "" (null string) refers to the current WIL
       interpreter window.

       Warning:  Some applications may rely upon their window's title staying
       the same!  Therefore, the WinTitle function should be used with
       caution and adequate testing.


       Example:
        ; Capitalize title of window
        htab = Num2Char(9)
        allwinds = WinItemize()
        mywin = ItemSelect("Uppercase Windows", allwinds, htab)
        WinTitle(mywin, StrUpper(mywin))
        Drop(htab, allwinds, mywin)


       See Also:
          WinGetActive, WinItemize, WinName




       WinVersion
       Provides the version number of the current Windows system.


       Syntax:
        WinVersion (level)

       Parameters:
        (i) level    either @MAJOR or @MINOR.

       Returns:
        (i)          either major or minor part of the Windows version
                     number.

       Use this command to determine which version of Windows is currently
       running.





       @MAJOR returns the integer part of the Windows version number; i.e.
       1.0, 2.11, 3.0, etc.

       @MINOR returns the decimal part of the Windows version number; i.e.
       1.0, 2.11, 3.0, etc.


       Example:
        minorver = WinVersion(@MINOR)
        majorver = WinVersion(@MAJOR)
        Message("Windows Version", StrCat(majorver, ".", minorver))


       See Also:
          Version, DOSVersion




       WinWaitClose
       Suspends the WIL program execution until a specified window has been
       closed.


       Syntax:
        WinWaitClose (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  WinWaitClose suspends execution until all
                     matching windows have been closed.

       Returns:
        (i)          @TRUE if at least one window was found to wait for;
                     @FALSE if no windows were found.

       Use this function to suspend the WIL program's execution until the
       user has finished using a given window and has manually closed it.


       Example:
        Run("clock.exe", "")
        Display(4, "Note", "Close Clock to continue")
        WinWaitClose("Clock")
        Message("Continuing...", "Clock closed")


       See Also:
          Delay, RunWait, WinExist, Yield




       WinZoom
       Maximizes a window to full-screen.






       Syntax:
        WinZoom (partial-winname)

       Parameters:
        (s) partial-winname     either an initial portion of, or an entire
                     window name.  The most-recently used window whose title
                     matches the name will be shown.

       Returns:
        (i)          @TRUE if a window was found to zoom;
                     @FALSE if no windows were found.

       Use this function to "zoom" windows to full screen size.

       A partial-window name of "" (null string) zooms the current WIL
       interpreter window.


       Example:
        Run("notepad.exe", "")
        WinZoom("Notepad")
        Delay(3)
        WinShow("Notepad")


       See Also:
          RunZoom, WinHide, WinIconize, WinPlace, WinShow




       Yield
       Provides time for other windows to do processing.


       Syntax:
        Yield

       Parameters:
        (none)

       Returns:
        (not applicable)

       Use this command to give other running windows time to process.  This
       command will allow each open window to process 20 or more messages.


       Example:
        ; run Excel and give it some time to start up
        sheet = AskLine ("Excel", "File to run:", "")
        Run("excel.exe", sheet)
        Yield
        Yield
        Yield






       See Also:
          Delay, Exclusive






                                    DIALOG BOXES

       For each dialog box, you must first create a template file, with a
       (recommended) WDG extension, which will identify the structure of the
       dialog box, as well as the variables used by it.  Unlike the other WIL
       functions, you do not actually pass variables to DialogBox as
       parameters.  However, the DialogBox function does indeed have the
       ability to manipulate, and even create, variables.  If you are
       familiar with programming, you may think of DialogBox as a subroutine,
       and all the variables it uses as being global.

       Let's start with a simple example.  Suppose we want to write a WIL
       program which starts up Notepad, with two options which can be
       selected at runtime:

       Here's what the template file will look like:

        [zoom+1Start editor zoomed]
        [backup+1Save backup of file]

       It is an ordinary ASCII file.

       Some explanation is in order.  First, note the square brackets.  Each
       element in a WDG file is enclosed in brackets; in this case, there are
       two distinct elements.  Next, notice that the first items that appear
       inside the brackets are variable names -- in this case, zoom and
       backup.  Immediately following the variable name is a plus sign (+),
       which identifies the elements as being check boxes.  After the +
       symbol is the number 1, which represents the value that will be
       assigned to the variable if the box gets checked.  Note that there is
       no space before or after the + symbol.  Finally, we have the text
       which will be displayed next to the check box.

       Now, let's create the WIL program file which will use this WDG
       template:

        file = ItemSelect("", FileItemize("*.*"), " ")
        DialogBox("Edit a file", "edit.wdg")
        If backup == 0 Then Goto nobackup
        filebackupname = StrCat(FileRoot(file), ".", "bak")
        FileCopy(file, filebackupname, @TRUE)
        :nobackup
        If zoom == 1 Then Run("notepad.exe", file)
        If zoom == 1 Then RunZoom("notepad.exe", file)

       The WDG template file should be in the current directory or in a
       directory on your path; otherwise, you must give a complete path
       specification for it when it appears in the DialogBox statement.

       Now, run the WIL program.  See how the lines in the template file got
       translated to fields in the dialog box.  Also notice the two buttons
       that were added at the bottom -- OK and Cancel.  Cancel terminates the
       WIL program entirely.

       You may want to try running this with various combinations of boxes
       checked, just to confirm that it works properly.  It should.





       Now, look again at the WIL program.  Notice how the variables zoom and
       backup do not appear until after the DialogBox statement.  In essence,
       these variables are created by the WDG template, and initialized with
       values of 0.  If the user checks a box, the variable associated with
       that box is given the value which appears next to the + symbol in the
       template.  So, if the first box is checked, then zoom will have a
       value of 1 after the DialogBox statement is executed.  If it remains
       un-checked, it will still have a value of 0.  These values can then be
       used in your WIL program, as we have done above.

       Suppose that you want a box to be checked, by default.  All you need
       to do is to assign a non-zero value to the corresponding variable
       before you execute the DialogBox statement.  For example:

        file = ItemSelect("", FileItemize("*.*"), " ")
        zoom = 1
        DialogBox("Edit a file", "edit.wdg")
        If backup == 0 Then Goto nobackup
        filebackupname = StrCat(FileRoot(file), ".", "bak")
        FileCopy(file, filebackupname, @TRUE)
        :nobackup
        If zoom == 0 Then Run("notepad.exe", file)
        If zoom == 1 Then RunZoom("notepad.exe", file)

       When you run it this time, the first box will already be checked,
       because we first assigned a value of 1 to the variable zoom.  The
       variable will still have a value of 1 after the DialogBox statement is
       executed -- unless the user un-checks the box, in which case it will
       have a value of 0.  The variable associated with an unchecked box is
       always equal to 0; the variable associated with a checked box is equal
       to the value you specify for that box.  For the most part, you would
       be fine simply using a value of 1 to indicate a checked box.

       You can change the layout of the WDG template to suit your taste.  For
       example, this:

        [zoom+1Start editor zoomed]   [backup+1Save backup of file]

       would put the two check boxes side by side.  However, you may not put
       tab characters in a template file, so be sure to use spaces instead
       (unless your editor can convert tabs to spaces).  Also, template files
       are limited to 20 lines, and to the first 60 columns

       The next element which you can use in a dialog box is the radio
       button.  Whereas you can have several check boxes checked at one time,
       the radio button gets its name from the five-button car radio, which
       can only have one station selected at a time.  You can have more than
       one group of radio buttons, but only one button in each group may be
       "pressed."  Therefore, this is ideal for situations where the user
       must make a choice from multiple alternatives:

       Here's a group of four radio buttons:

        [editor^1Notepad]       [editor^2WinEdit]
        [editor^3Write]         [editor^4WinWord]





       Let's look at how these are different from check boxes.  First, the
       symbol which identifies a radio button is a caret (^), instead of a +.
       Second, each of the buttons has the same variable name (editor).  And
       third, each button has a unique value following the ^ symbol.

       This should make sense if you consider what we are trying to
       accomplish: we want to obtain a value for the variable editor.  The
       user has four programs to choose from, and he must choose one, and
       only one.  As you have probably guessed, the value associated with the
       button which the user "pushes" will be assigned to editor.

       Let's add this to our existing EDIT.WDG template:

        [zoom+1Start editor zoomed]
        [backup+1Save backup of file]
        [editor^1Notepad]       [editor^2WinEdit]
        [editor^3Write]         [editor^4WinWord]

       and expand our WIL program to take advantage of it:

        file = ItemSelect("", FileItemize("*.*"), " ")
        zoom = 1
        DialogBox("Edit a file", "edit.wdg")
        If backup == 0 Then Goto nobackup
        filebackupname = StrCat(FileRoot(file), ".", "bak")
        FileCopy(file, filebackupname, @TRUE)
        :nobackup
        If zoom == 0 Then runcmd = "Run"
        If zoom == 1 Then runcmd = "RunZoom"
        If editor == 1 Then %runcmd%("notepad.exe", file)
        If editor == 2 Then %runcmd%("winedit.exe", file)
        If editor == 3 Then %runcmd%("write.exe", file)
        If editor == 4 Then %runcmd%("winword.exe", file)

       (We're using the variable runcmd to avoid having to code eight
       separate Run and RunZoom statements.  Pretty clever, isn't it.)

       Look at how we are testing the value of editor to determine which
       program to run.  When the DialogBox statement is executed, the first
       radio button in each group is selected, regardless of its value.  In
       this case, the first button appearing in the template, in the editor
       group, has a value of 1, so, unless the user selects a different
       button, the variable editor will have a value of 1 after DialogBox
       finishes, and Notepad will be run.  If the user selects the WinEdit
       button, editor will have a value of 2 , and Winedit will be run.

       Another important element which you can use in your templates is the
       file selection list box, which combines the functionality of
       DirItemize, FileItemize, and ItemSelect.  It has the following form:

        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]





       Here, file is the variable name (you can use another name instead of
       file), and the backslash (\) is the symbol which identifies this as a
       file list element.  The amount of space between the \ symbol and the
       right bracket will determine the width of the file selection list box.
       And the number of occurrences of this element (each must have an
       identical name) will determine the height of the list box.

       Let's add this to our template:

        [zoom+1Start editor zoomed]
        [backup+1Save backup of file]
        [editor^1Notepad]       [editor^2WinEdit]
        [editor^3Write]         [editor^4WinWord]
        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]

       and revise our program:

        zoom = 1
        DialogBox("Edit a file", "edit.wdg")
        If backup == 0 Then Goto nobackup
        filebackupname = StrCat(FileRoot(file), ".", "bak")
        FileCopy(file, filebackupname, @TRUE)
        :nobackup
        If zoom == 0 Then runcmd = "Run"
        If zoom == 1 Then runcmd = "RunZoom"
        If editor == 1 Then %runcmd%("notepad.exe", file)
        If editor == 2 Then %runcmd%("winedit.exe", file)
        If editor == 3 Then %runcmd%("write.exe", file)
        If editor == 4 Then %runcmd%("winword.exe", file)

       All we did was remove the first line from the earlier example, which
       used FileItemize and ItemSelect to retrieve a file name.

       By default, the file selection list box uses *.* as a file mask.  If
       you want to limit the selection to, say, DOC files, assign a value to
       the appropriate variable before executing the DialogBox statement:

        file = "*.doc"
        DialogBox("Edit a file", "edit.wdg")

       Another element, the file mask edit box, allows the user to change the
       file mask interactively.  It's format is:

        [file#        ]

       Where the variable name, in this case file, must be the same as the
       one used in the file selection list box, and is followed by a number
       sign (#).  If the user enters a valid wild card mask in the file mask
       edit box, the file display in the file selection list box will be
       updated accordingly.  For example, if DOC files are currently shown,
       and the user types *.TXT, the display will change to show TXT files.





       You can optionally display the current directory (whose contents are
       being listed) by including an additional element in the template:

        [file$                       ]

       This is identical to the file list element, except the symbol for the
       directory element is a dollar sign ($).  The variable name must be the
       same as the one used in the file selection list box:

        [file$                       ]
            File mask [file#         ]
        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]
        [file\                       ]

       Note that we have included the descriptive text "File mask" next to
       the file mask edit box.  You may place explanatory text anywhere in
       the template file, as long as it doesn't appear inside square
       brackets.

       You can also display a WIL variable in your dialog box by using an
       element of this form:

        [varname$]

       Where the name of the variable is followed by a dollar sign ($).  The
       WIL Interpreter will replace this with the current value of the
       variable.

       Finally, we have the edit box, which allows us to assign user-supplied
       text to a variable.  The edit box element has the form:

        [input#                      ]

       The variable name (in this case, input) is followed a number sign (#),
       and the width of the area between the brackets determines the width of
       the edit box which gets displayed.  Whatever the user types in the box
       gets assigned to the associated variable.  Here is a sample RENAME.WDG
       template:

        Select file to be renamed
        [oldname$                         ]
        [oldname\                         ]
        [oldname\                         ]
        [oldname\                         ]
        [oldname\                         ]

        Type new name for the file
        [newname#                         ]

       Which could be used with this program:

        DialogBox("File Rename", "rename.wdg")
        FileRename(oldname, newname)





       You will have noticed that there are two symbols -- $ and # -- which
       have dual meanings, depending on whether or not there is a file list
       selection variable in the template with the same name.  The three file
       elements -- [file\], [file$], and [file#] -- are a "set", and share a
       common variable name.  All other variables in your template should
       have unique names.






                                     APPENDIX A

                                Predefined Constants

       WIL provides you with a number of predefined integer constants to help
       make your WIL programs more mnemonic:


       Logical Conditions                    String Handling
       @FALSE                                @FWDSCAN
       @NO                                   @BACKSCAN
       @OFF
       @TRUE                                 Menu Handling
       @YES                                  @ENABLE
       @ON                                   @DISABLE
                                             @UNCHECK
       Window Arranging                      @CHECK
       @NORESIZE
       @ABOVEICONS                           System Control
       @STACK                                @MAJOR
       @ARRANGE                              @MINOR
       @TITLE
       @ROWS                                 Error Handling
       @COLUMNS                              @CANCEL
                                             @NOTIFY
                                             @OFF

                                             Keyboard Status
                                             @SHIFT
                                             @CTRL

                                             Debug Control
                                             @PARSEONLY







                                     APPENDIX B

                                       Errors

       If the current error mode is @CANCEL (the default), any WIL errors
       encountered while processing a WIL program cause the item to be
       canceled with an error message.




       Minor Errors
       Minor errors are ignored if the current error mode has been set to
       @OFF.  If the error mode is @NOTIFY the user has the option of
       continuing with the WIL program or canceling it.

       1006 File Copy/Move: No matching files found
       1017 File Delete: No matching files found
       1018 File Delete: Delete Failed
       1024 File Rename: No matching files found
       1025 File Rename: Rename failed
       1028 LogDisk: Requested drive not online
       1029 DirMake: Dir not created
       1030 DirRemove: Dir not removed
       1031 DirChange: Dir not found/changed
       1039 WinClose: Window not found
       1040 WinHide: Window not found
       1041 WinIconize: Window not found
       1042 WinZoom: Window not found
       1043 WinShow: Window not found
       1044 WinPlace: Window not found
       1045 WinActivate: Window not found
       1077 FileOpen: Open failed
       1119 WinPosition: Window not found
       1121 WinTitle: Window not found
       1100 StrIndex/StrScan 3rd parameter out of bounds





       1900 WinExec 0: Out of Memory
       1902 WinExec 2: File Not Found
       1903 WinExec 3: Path Not Found
       1905 WinExec 5: Attempt to dynlink to a task
       1906 WinExec 6: Lib requires data segs for each task
       1910 WinExec 10: Incorrect Windows Version
       1911 WinExec 11: Invalid EXE file
       1912 WinExec 12: Cannot run OS/2 application
       1913 WinExec 12: Cannot run DOS4.0 application
       1914 WinExec 14: Unknown EXE type
       1915 WinExec 15: Attempt to run old EXE in protect mode
       1916 WinExec 16: Attempted 2nd EXE with multiple writeable datasegs
       1917 WinExec 17: Nonshareable DLLs already in use
       1918 WinExec 18: App marked for protected mode only
       1932 WinExec: Undefined Error



       Moderate Errors
       If the error mode is @NOTIFY or @OFF, the user has the option of
       continuing with the WIL program or canceling it.

       2001 SendKey: Illegal Parameters
       2002 File Copy/Move: 'From' file illegal
       2003 File Copy/Move: 'To'   file illegal
       2004 File Copy/Move: Cannot copy/move wildcards into fixed root
       2005 File Copy/Move: Cannot copy/move wildcards into fixed extension
       2007 File Move: Unable to rename source file
       2015 File Move:  Unable to remove source file
       2016 File Delete: File name illegal
       2019 File Rename: 'From' file illegal
       2020 File Rename: 'To' file illegal
       2021 File Rename: Attempt to rename across drive boundary. - Use MOVE
            instead.
       2022 File Rename: Cannot rename wildcards into a fixed filename root
       2023 File Rename: Cannot rename wildcards into a fixed filename
            extension
       2038 WinCloseNot Function Syntax error
       2045 WinActivate: Window not found
       2058 StrCat function syntax error
       2060 Average function syntax error
       2093 Dialog Box: Bad Filespec, using *.*
       2112 FileSize: File Not Found
       2118 FileCopy/Move: Destination file same as source



       Fatal Errors
       Fatal errors cause the current WIL program to be canceled with an
       error message, regardless of the error mode in effect.  (We show the
       error codes here for consistency, but in practice you will never be
       able to call LastError after a fatal error.)

       3008 File Copy/Move: 'From' file open error
       3009 SendKey: Could not open DEBUG text file
       3010 SendKey: Could not install hook - Already Active??
       3011 File Copy/Move: 'From' file length error





       3012 File Copy/Move: No room left on disk.  Out of space??
       3013 File Copy/Move: 'To' file open error
       3014 File Copy/Move: I/O Error
       3015 File Move:  Unable to remove source file
       3026 LogDisk: Illegal disk drive
       3027 LogDisk: DOS reports no disks!!  ???
       3032 GoTo unable to lock memory for batch file
       3033 GoTo label not found
       3034 Clipboard owned by another app.  Cannot open.
       3035 Clipboard does not contain text for ClipAppend.
       3036 Clipboard cannot hold that much text (>64000 bytes)
       3037 Unable to allocate memory for clipboard.  Close some applications
       3046 Internal Error 3046. Function not defined
       3047 Variable name over 30 chars. Too Long
       3048 Substitution %Variable% not followed by % (Use %% for %)
       3049 No variables exist??!!
       3050 Undefined variable
       3051 Undefined variable or function
       3052 Uninitialized variable or undefined function
       3053 Character string too long (>256 chars??)
       3054 Unrecognizable item found on line
       3055 Variable name is over 30 chars. Too Long
       3056 Variable could not be converted to string
       3057 Variable could not be converted to integer
       3059 Illegal Bounds for StrSub function
       3061 Illegal Syntax
       3062 Attempt to divide by zero
       3063 Internal Error 3063. Binary op not found
       3064 Internal Error 3064. Unary op not found
       3065 Unbalanced Parenthesis
       3066 Wrong Number of Arguments in Function
       3067 Function Syntax. Opening parenthesis missing.
       3068 Function Syntax. Illegal delimiter found.
       3069 Illegal assignment statement. (Use == for equality testing)
       3070 Internal error 3070.  Too many arguments defined.
       3071 Missing or incomplete statement
       3072 THEN not found in IF statement
       3073 Goto Label not specified
       3074 Expression continues past expected end.
       3075 Call: Parse of file/parameter line failed
       3076 FileOpen: READ or WRITE not properly specified
       3078 FileOpen: Too many (>5) files open
       3079 FileClose: Invalid file handle
       3080 FileClose: File not currently open
       3081 FileRead: Invalid file handle
       3082 FileRead: File not currently open
       3084 FileWrite: Invalid file handle
       3085 FileWrite: File not currently open
       3087 FileRead:  File not open for reading
       3088 FileRead: Attempt to read past end of file
       3089 FileWrite: File not open for writing
       3090 Dialog Box: File open error
       3091 Dialog Box: Box too large
       3092 Dialog Box: Non-text control used w/filebox.
       3094 Dialog Box: Window Registration Failed
       3095 Compare could not be resolved into a integer or string compare
       3096 Memory allocation failure.  Out of memory for string storage





       3097 Memory allocation failure.  Out of memory for variable storage
       3098 Internal error, NULL pointer passed to xstrxxx subroutines
       3099 CallExt function disabled.  Not currently available.
       3101 Substituted line too long. (> 256 characters)
       3102 Drop: Can only drop variables
       3103 IsDefined: Attempting to test non-variables item
       3104 Dialog Box: Window Creation Failed
       3105 Batch Compiler:  CALL and CALLEXT not supported in compiled EXE
            versions
       3107 Run: Filetype is not COM, EXE, PIF or BAT
       3108 FileItemize: Unable to lock file info segment
       3109 FileItemize: Unable to unlock file info segment
       3110 FileItemize: Unable to lock file index segment
       3111 FileItemize: Unable to unlock file index segment
       3113 FileSize: Filelength I/O Error
       3114 FileSize: Buffer Overrun Error
       3115 FileDelete: Buffer Overrun Error
       3116 FileRename: Buffer Overrun Error
       3117 FileCopyMove: Buffer Overrun Error






                                     APPENDIX A

                                       Browser

       The Command Post Browser program lets you view a file's contents in a
       variety of ways.

       The default is to show the file in Windows' "ANSI text" mode:






       Initial Browser View - ANSI Text

       As you can see, Browser gives you five main menus to choose from:


       File
       These menu items let you open a new file to view, re-read the current
       file, and perform other housekeeping functions including exiting the
       program.


       Hide & Seek
       Browser gives you the ability to filter which lines you view with its
       Hide & Seek commands.  You can hide or show specific lines by entering
       a word to look for.

       For instance, the menu item Hide & Seek/Show if... displays this
       dialog box:






       ...and (in this example) shows only the lines containing the word
       "modem":







       Print
       These selections allow you to print all or part of the file.


       Clip Copy
       Lets you copy portions of the file into the Windows Clipboard.


       Clip Append
       Lets you add portions of the file onto the end of the Windows
       Clipboard.


       Options
       These menu items let you change how you view the file; changing for
       example between ASCII text mode (which interprets some special
       characters differently than ANSI text) and hex-dump formats:






                 Options/ASCII text                 Options/Hex dump